{ "openapi": "3.1.0", "info": { "title": "Vastgoed.ai API", "version": "1.5.0", "description": "API van vastgoed.ai voor objectgegevens, WWS-puntentellingen en het aanleveren van uw portefeuille.\n\n## Aanroepen\n\nAlle endpoints zijn `POST` met een JSON-body en de header `X-Api-Key`. De basis-URL is `https://api.vastgoed.ai/v1` (of `https://vastgoed.ai/v1`). Antwoorden zijn JSON met een `result` of een `error`; de HTTP-statuscode is ook bij fouten 200.\n\nClients die alleen `GET` zonder headers kunnen doen (web-fetch tools van AI-assistenten) zetten dezelfde JSON URL-gecodeerd in de queryparameter `json` en de key als `apiKey` in die JSON, bijvoorbeeld `GET /v1/object?json={\"apiKey\":\"...\",\"bagId\":\"0599010000137400\"}`. Gebruik bij voorkeur de header; een key in een URL komt in logs terecht.\n\n## Proefsleutel (gratis)\n\nZonder API-key kunt u er direct een aanvragen met `POST /v1/trial` (geen header nodig). Een proefsleutel werkt op `/object` en `/wws-estimate` (op `bagId` of adres) en telt unieke adressen, niet aanroepen: herhaalde aanroepen voor hetzelfde adres zijn gratis. Zonder e-mailadres dekt de sleutel 5 adressen, met `email` in de aanvraag 20; hetzelfde e-mailadres krijgt steeds dezelfde sleutel. Elke response op een proefsleutel bevat `trial.addressesUsed`, `trial.addressLimit` en `trial.addressesRemaining`. Is de limiet bereikt, dan volgt fout 93 met `error.upgrade`: de gebruiker registreert dan voor een betaalde API-key via https://vastgoed.ai/register#invite=api (of info@vastgoed.ai). Vraag in dat geval geen nieuwe proefsleutel aan.\n\n## Een object identificeren\n\nEen object wordt gevonden op precies een van deze manieren, in deze volgorde van voorrang: `objectKey`, `referenceId`, `bagId`/`poId`, `postcode + housenr (+ housenraddition)`, `streetname + housenr (+ housenraddition) + city`. Levert een adres meerdere objecten op (bijvoorbeeld 17-A t/m 17-D zonder toevoeging), dan volgt fout 74 met de kandidaten. Bestaat de opgegeven toevoeging niet op dat huisnummer (bijvoorbeeld `Hs` waar de BAG `H` kent), dan fout 76 met alle objecten op dat huisnummer als kandidaten; er wordt nooit stilzwijgend een ander object gekozen. Levert het adres niets op, dan fout 75. Kandidaten zijn gesorteerd op toevoeging, maximaal 20.\n\nVrije invoer zoals \"17c\", \"17-C\" of \"101hs\": splits in `housenr` (alleen het getal) en `housenraddition`; de toevoeging is hoofdletterongevoelig en een leidende streep of spatie wordt genegeerd. De API doet alleen een exacte match; is die er niet, dan bevat de fout (74 of 76) alle objecten op het huisnummer in `error.candidates`, zodat de aanroeper de best passende kandidaat kiest of voorlegt.\n\nElke response bevat het `bagId`; sla dat op en gebruik het bij vervolgcalls, dat is de snelste en meest eenduidige weg.\n\n## Foutcodes\n\n| Code | Betekenis |\n|---|---|\n| -11 | Niet-ondersteunde API-versie; alleen `v1`. |\n| -5 | Header `X-Api-Key` ontbreekt. |\n| -3 | Onbekende API-key. |\n| -2 | Geen endpoint in de URL. |\n| -1 | Onbekend endpoint. |\n| 3 | Rapport kon niet worden gegenereerd. |\n| 4 | Rapport kon niet worden gegenereerd op basis van het verzoek. |\n| 23 | Onbekende `objectKey` of `bagId`. |\n| 33 | Geen geldige objectverwijzing (`bagId`, adres of `objectKey`). |\n| 34 | `account.email` ontbreekt. |\n| 36 | Onbekende gebruiker voor `account.email`. |\n| 37 | Onbekende `objectKey`. |\n| 39 | Object kon niet worden opgeslagen. |\n| 44 | `/wws-report` op een schattingsobject; gebruik `/wws-estimate`. |\n| 72 | `wwsId`, `properties.roomsMeasured` of `properties.outsideMeasured` niet ondersteund op `/wws-estimate`. |\n| 73 | Object niet gevonden, of `/wws-report` op `bagId` (alleen `objectKey`/`referenceId`). |\n| 74 | Adres levert meerdere objecten op; zie `error.candidates`. Geef `housenraddition` mee of gebruik `bagId`. |\n| 75 | Adres niet gevonden. |\n| 76 | Toevoeging bestaat niet op dit huisnummer; zie `error.candidates` voor de objecten die er wel zijn. |\n| 78 | Geen rapport beschikbaar voor het object. |\n| 79 | Rapport niet beschikbaar; `devMessage` bevat de reden (bijvoorbeeld geen woningobject). |\n| 89 | `objectKey` ontbreekt (`/account-contract`). |\n| 90 | Betaald endpoint (`/floorplan`, `/building`) of betaalde optie (`energyLabelHistory` op `/object`) niet geactiveerd voor deze API-key; `error.activation` bevat de URL om activatie aan te vragen. |\n| 91 | `objectKey` en `scorings[]` verplicht (`/account-wws-import`). |\n| 92 | Onbekende `objectKey` of geen toegang. |\n| 93 | Proefsleutel: limiet van unieke adressen bereikt; eerder opgevraagde adressen blijven beschikbaar. Registreer voor een betaalde API-key via `error.upgrade`. |\n| 94 | Proefsleutel: te veel proefsleutels aangevraagd vanaf dit netwerk; registreer via `error.upgrade`. |\n| 95 | Proefsleutel: endpoint of `objectKey`/`referenceId` niet beschikbaar op een proefsleutel (alleen `/object` en `/wws-estimate` op `bagId` of adres). |\n| 102 | Onbekende identificatie voor `/object`. |\n", "termsOfService": "https://vastgoed.ai/api-terms", "contact": { "name": "vastgoed.ai", "email": "info@vastgoed.ai", "url": "https://vastgoed.ai" }, "license": { "name": "Proprietary", "url": "https://vastgoed.ai/api-terms" } }, "servers": [ { "url": "https://api.vastgoed.ai/v1" }, { "url": "https://vastgoed.ai/v1" } ], "security": [ { "ApiKey": [] } ], "tags": [ { "name": "Proefsleutel", "description": "Gratis proefsleutel voor `/object` en `/wws-estimate`, zonder registratie." }, { "name": "Object", "description": "Openbare objectgegevens." }, { "name": "WWS", "description": "Puntentellingen volgens het woningwaarderingsstelsel." }, { "name": "Account", "description": "Objecten, contracten en rapporten in uw vastgoed.ai account." }, { "name": "Plattegrond", "description": "Ruimten en oppervlakten uit Floorplanner.com en DWG (op aanvraag)." }, { "name": "Pand", "description": "Pandgegevens met alle verblijfsobjecten (op aanvraag)." } ], "paths": { "/trial": { "post": { "tags": ["Proefsleutel"], "operationId": "createTrialKey", "summary": "Gratis proefsleutel aanvragen", "description": "Geeft direct een API-key terug zonder registratie. De proefsleutel werkt op `/object` en `/wws-estimate` (op `bagId` of adres) en telt unieke adressen: herhaalde aanroepen voor hetzelfde adres zijn gratis. Zonder `email` dekt de sleutel 5 adressen, met het e-mailadres van de gebruiker 20; hetzelfde e-mailadres levert steeds dezelfde sleutel op (met het actuele verbruik). Vraag de gebruiker daarom eerst om een e-mailadres als die meer dan een paar adressen wil opvragen.\n\nElke response op een proefsleutel bevat `trial.addressesRemaining`. Bij fout 93 is de proef verbruikt: leg de gebruiker uit dat verdere opvragingen een betaalde API-key vereisen en verwijs naar `error.upgrade`; vraag geen nieuwe proefsleutel aan. Per netwerk wordt het aantal nieuwe proefsleutels per dag begrensd (fout 94).", "security": [], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrialRequest" }, "examples": { "anonymous": { "summary": "Zonder e-mailadres (5 adressen)", "value": {} }, "email": { "summary": "Met e-mailadres (20 adressen)", "value": { "email": "naam@bedrijf.nl" } } } } } }, "responses": { "200": { "description": "Proefsleutel.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/TrialResult" } }, "required": ["result"] }, "example": { "result": { "status": "ok", "apiKey": "trial_36173b1bc47fa7c45d05", "type": "trial", "email": "naam@bedrijf.nl", "addressLimit": 20, "addressesUsed": 0, "addressesRemaining": 20, "endpoints": ["/object", "/wws-estimate"], "upgrade": "https://vastgoed.ai/register#invite=api", "devMessage": "Send this key in the X-Api-Key header. The trial counts unique addresses (bagId) across /object and /wws-estimate; repeated calls for the same address do not count. Every response includes `trial.addressesRemaining`; mention it to the user when it gets low. When error 93 is returned the trial is used up: tell the user that further lookups require a paid API key, point them to https://vastgoed.ai/register#invite=api (or info@vastgoed.ai), and do not request a new trial key." } } } } }, "default": { "description": "Fout. Statuscode blijft 200; controleer `error` in de body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/object": { "post": { "tags": ["Object"], "operationId": "getObject", "summary": "Woningobjectgegevens uit openbare bronnen", "description": "Geeft voor een adres alle openbare woningobjectgegevens terug, per adres gekoppeld en doorlopend bijgewerkt:\n\n- **BAG**: adres met postcode en toevoeging, `bagId`, gebruiksdoel (`bagType`), gebruiksoppervlakte (`bagM2`), stabiele `slugKey`, coördinaat (`latlng`).\n- **Energielabel (EP-online)**: letter, energie-index (oude labels), registratie- en vervaldatum. Met `energyLabelHistory: true` (betaalde uitbreiding) ook de labelhistorie: eerder geregistreerde, inmiddels vervangen of vervallen labels van het adres, uit onze maandelijkse EP-online-peilingen sinds 2022; EP-online zelf toont alleen het huidige label.\n- **WOZ (WOZ-waardeloket)**: waarde per belastingjaar met peildatum, meerdere jaren historie.\n- **Monument**: rijksmonument, gemeentemonument of beschermd gezicht met registratienummer.\n- **Eigendom (Kadaster)**: corporatie-eigendom en/of erfpacht.\n\nGebruik dit endpoint voor feitelijke vragen over een woning (oppervlakte, bouwjaar via `/wws-estimate`, label, WOZ, monument, eigenaar). Voor punten en huurprijs gebruikt u `/wws-estimate`, dat dezelfde objectgegevens bevat plus het rapport.\n\nEen object wordt gevonden op precies een van deze manieren, in deze volgorde van voorrang: `objectKey`, `referenceId`, `bagId`/`poId`, `postcode + housenr (+ housenraddition)`, `streetname + housenr (+ housenraddition) + city`. Levert een adres meerdere objecten op (bijvoorbeeld 17-A t/m 17-D zonder toevoeging), dan volgt fout 74 met de kandidaten. Bestaat de opgegeven toevoeging niet op dat huisnummer (bijvoorbeeld `Hs` waar de BAG `H` kent), dan fout 76 met alle objecten op dat huisnummer als kandidaten; er wordt nooit stilzwijgend een ander object gekozen. Levert het adres niets op, dan fout 75. Kandidaten zijn gesorteerd op toevoeging, maximaal 20.", "requestBody": { "required": true, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectLookupRequest" }, "examples": { "bagId": { "summary": "Op bagId", "value": { "bagId": "0599010000137400" } }, "energyLabelHistory": { "summary": "Op bagId, met labelhistorie (betaalde uitbreiding)", "value": { "bagId": "0599010000137400", "energyLabelHistory": true } }, "postcode": { "summary": "Op postcode en huisnummer", "value": { "postcode": "3013CB", "housenr": 17, "housenraddition": "C" } }, "streetname": { "summary": "Op straat, huisnummer en plaats", "value": { "streetname": "Weena", "housenr": 17, "housenraddition": "C", "city": "Rotterdam" } }, "objectKey": { "summary": "Op objectKey", "value": { "objectKey": "2fqgqz6zqc5hf85irzzqdd3adfa3d" } }, "referenceId": { "summary": "Op eigen referenceId", "value": { "referenceId": "PROP-11928" } } } } } }, "responses": { "200": { "description": "Objectgegevens.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/ObjectResult" }, "trial": { "$ref": "#/components/schemas/TrialUsage" } }, "required": ["result"] }, "example": { "result": { "status": "ok", "bagId": "0599010000137400", "title": "Weena 17-C, Rotterdam", "address": { "streetname": "Weena", "housenr": 17, "housenraddition": "C", "city": "Rotterdam", "postcode": "3013CB", "country": "nl", "slugKey": "rotterdam-weena-ivapma" }, "properties": { "bagType": "residential", "bagM2": 79 }, "energyLabel": { "letter": "A", "index": false, "registration": "2025-04-29", "expire": "2035-04-10" }, "monument": [], "ownership": [], "woz": [ { "year": 2026, "snapshot": "2025-01-01", "value": 416000 }, { "year": 2025, "snapshot": "2024-01-01", "value": 435000 }, { "year": 2024, "snapshot": "2023-01-01", "value": 438000 }, { "year": 2023, "snapshot": "2022-01-01", "value": 442000 }, { "year": 2022, "snapshot": "2021-01-01", "value": 386000 }, { "year": 2021, "snapshot": "2020-01-01", "value": 352000 }, { "year": 2020, "snapshot": "2019-01-01", "value": 329000 } ], "latlng": { "lat": 51.92499746298337, "lng": 4.476839361191538 } } } } } }, "default": { "description": "Fout. Statuscode blijft 200; controleer `error` in de body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/wws-estimate": { "post": { "tags": ["WWS"], "operationId": "getWwsEstimate", "summary": "WWS-puntenrange op basis van openbare data", "description": "Berekent een bandbreedte van WWS-punten en de bijbehorende maximale huurprijs op basis van openbare data (BAG, EP-online, WOZ, monumentenregister). Optioneel kunt u `properties.measuredM2` en `properties.outsideMeasuredM2` meesturen als hint; die vervangen dan de BAG-oppervlakte.\n\nNiet ondersteund op dit endpoint (fout 72): `wwsId`, `properties.roomsMeasured`, `properties.outsideMeasured`. Gebruik daarvoor `/wws-report`.\n\nEen object wordt gevonden op precies een van deze manieren, in deze volgorde van voorrang: `objectKey`, `referenceId`, `bagId`/`poId`, `postcode + housenr (+ housenraddition)`, `streetname + housenr (+ housenraddition) + city`. Levert een adres meerdere objecten op (bijvoorbeeld 17-A t/m 17-D zonder toevoeging), dan volgt fout 74 met de kandidaten. Bestaat de opgegeven toevoeging niet op dat huisnummer (bijvoorbeeld `Hs` waar de BAG `H` kent), dan fout 76 met alle objecten op dat huisnummer als kandidaten; er wordt nooit stilzwijgend een ander object gekozen. Levert het adres niets op, dan fout 75. Kandidaten zijn gesorteerd op toevoeging, maximaal 20.", "requestBody": { "required": true, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WwsEstimateRequest" }, "examples": { "bagId": { "summary": "Op bagId", "value": { "bagId": "0599010000137400" } }, "postcode": { "summary": "Op postcode en huisnummer", "value": { "postcode": "3013CB", "housenr": 17, "housenraddition": "C" } }, "streetname": { "summary": "Op straat, huisnummer en plaats", "value": { "streetname": "Weena", "housenr": 17, "housenraddition": "C", "city": "Rotterdam" } }, "hints": { "summary": "Met gemeten oppervlakte als hint", "value": { "bagId": "0599010000137400", "properties": { "measuredM2": 90, "outsideMeasuredM2": 8 } } }, "raw": { "summary": "Ongefilterd rapport", "value": { "bagId": "0599010000137400", "output": "raw" } } } } } }, "responses": { "200": { "description": "Objectgegevens met schattingsrapport.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/ReportResult" }, "trial": { "$ref": "#/components/schemas/TrialUsage" } }, "required": ["result"] }, "example": { "result": { "status": "ok", "bagId": "0599010000137400", "title": "Weena 17-C, Rotterdam", "address": { "streetname": "Weena", "housenr": 17, "housenraddition": "C", "city": "Rotterdam", "postcode": "3013CB", "country": "nl", "slugKey": "rotterdam-weena-ivapma" }, "properties": { "bagType": "residential", "bagM2": 79 }, "latlng": { "lat": 51.92499746298337, "lng": 4.476839361191538 }, "report": { "settings": { "generated": 1787124273, "period": "2026", "year": 2026 }, "points": { "rooms": 71, "otherRooms": 0, "climate": 10, "energyLabel": 37, "kitchen": 7, "sanitary": 8, "outside": 4, "parking": 0, "sharedRooms": 0, "woz": 46.5, "label": "184 pt - 197 pt", "range": { "min": 184, "max": 197 } }, "energyLabel": { "label": "Energielabel A", "valid": true, "derived": { "registration": "2025-04-29", "expire": "2035-04-10", "notice": false } }, "woz": { "label": "€ 416.000", "amount": 416000, "derived": { "date": "Peildatum 2025-01-01", "label": "Peildatum 2025-01-01", "calculation": "(416000 / 16954) + (416000 / 71 / 268)" } }, "sector": { "regulated": true, "label": "Middenhuursegment of vrijehuursector", "ids": ["MIDDLE", "HIGH"], "likely": "HIGH" }, "building": { "monument": false, "buildYear": 1984 }, "price": { "label": "€ 1.214,31 - markthuur", "derived": { "percentalIncrease": 0 }, "range": { "min": 1214.31, "max": 1303.57 } }, "confidence": { "sector": 0.85, "regulation": 0.15 } } } } } } }, "default": { "description": "Fout. Statuscode blijft 200; controleer `error` in de body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/wws-report": { "post": { "tags": ["WWS"], "operationId": "getWwsReport", "summary": "Opgeslagen WWS-rapport van een object in uw account", "description": "Geeft de puntentelling terug van een object dat via `/account-object` (of in de vastgoed.ai omgeving) in uw account staat. Alleen op te vragen met `objectKey` of `referenceId`; een `bagId` geeft fout 73 (gebruik daarvoor `/wws-estimate`).\n\nZonder `properties` wordt het opgeslagen rapport gebruikt: standaard de meest recente revisie van type `lock` of `concept`; met `type: \"lock\"` alleen vastgestelde rapporten; met `wwsId` een specifieke revisie; met `unitKey` de telling van een onzelfstandige eenheid (kamer).\n\nMet `properties` (het volledige WWS-kenmerkenmodel, zie `WwsProperties`) wordt live een telling op uw eigen kenmerken berekend, aangevuld met de openbare data van het object (energielabel, WOZ, monument). Deze telling wordt niet opgeslagen.", "requestBody": { "required": true, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WwsReportRequest" }, "examples": { "objectKey": { "summary": "Op objectKey", "value": { "objectKey": "2fqgqz6zqc5hf85irzzqdd3adfa3d" } }, "referenceId": { "summary": "Op eigen referenceId", "value": { "referenceId": "PROP-11928" } }, "lock": { "summary": "Alleen vastgestelde rapporten", "value": { "objectKey": "2fqgqz6zqc5hf85irzzqdd3adfa3d", "type": "lock" } }, "unit": { "summary": "Onzelfstandige eenheid", "value": { "objectKey": "2fqgqz6zqc5hf85irzzqdd3adfa3d", "unitKey": "kamer-1" } }, "live": { "summary": "Live telling op eigen kenmerken", "value": { "objectKey": "2fqgqz6zqc5hf85irzzqdd3adfa3d", "properties": { "roomsMeasured": [ { "label": "Woonkamer", "value": 40, "heated": 1 }, { "label": "Slaapkamer", "value": 20, "heated": 1 } ], "kitchens": [ { "aanrecht": "LangerDanTwee", "kookplaat": "Inductie", "oven": "Electrisch", "koelkast": 1, "vaatwasmachine": 1 } ], "sanitaries": [ { "toilet": "SeperaatHangend", "badDouche": "Douche", "wastafel": 1 } ] } } } } } } }, "responses": { "200": { "description": "Objectgegevens met rapport. `report.pdf` verwijst naar het PDF-rapport, `report.details` bevat o.a. `wwsId`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/ReportResult" } }, "required": ["result"] } } } }, "default": { "description": "Fout. Statuscode blijft 200; controleer `error` in de body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/account-object": { "post": { "tags": ["Account"], "operationId": "upsertAccountObject", "summary": "Object aanmaken of bijwerken in uw account", "description": "Voegt een object toe aan het vastgoed.ai account van `account.email`, of werkt een bestaand object bij. Bestaat het `bagId` al in dat account, dan wordt de bestaande `objectKey` teruggegeven.\n\nAanmaken: `bagId` (of een adres, zie hieronder) plus `account.email`. Bijwerken: `objectKey`.\n\nMet `type: \"unit\"` en `reference` wordt een onzelfstandige eenheid (kamer) aan het object toegevoegd; het object wordt dan `onzelfstandig`. `reference` (uw eigen id, later bruikbaar als `referenceId`), `owner` en `properties.measuredM2` / `properties.outsideMeasuredM2` worden op het object opgeslagen.\n\nAdres in plaats van `bagId`: `postcode + housenr (+ housenraddition)` of `streetname + housenr (+ housenraddition) + city`; meerdere treffers geven fout 74, geen treffer fout 75.", "requestBody": { "required": true, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountObjectRequest" }, "examples": { "create": { "summary": "Aanmaken op bagId", "value": { "bagId": "0599010000137400", "reference": "PROP-11928", "owner": "Midvast BV", "account": { "email": "info@example.nl" } } }, "createAddress": { "summary": "Aanmaken op postcode en huisnummer", "value": { "postcode": "3013CB", "housenr": 17, "housenraddition": "C", "reference": "PROP-11928", "account": { "email": "info@example.nl" } } }, "unit": { "summary": "Kamer toevoegen", "value": { "bagId": "0599010000137400", "type": "unit", "reference": "kamer-1", "label": "Kamer 1", "account": { "email": "info@example.nl" } } }, "update": { "summary": "Bijwerken op objectKey", "value": { "objectKey": "2fqgqz6zqc5hf85irzzqdd3adfa3d", "reference": "PROP-11928", "properties": { "measuredM2": 60, "outsideMeasuredM2": 4 } } } } } } }, "responses": { "200": { "description": "De `objectKey` van het object (en `unitKey` bij een eenheid).", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/AccountObjectResult" } }, "required": ["result"] }, "example": { "result": { "objectKey": "2fqgqz6zqc5hf85irzzqdd3adfa3d" } } } } }, "default": { "description": "Fout. Statuscode blijft 200; controleer `error` in de body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/account-contract": { "post": { "tags": ["Account"], "operationId": "upsertAccountContracts", "summary": "Huurcontracten aanleveren voor een object", "description": "Slaat huurcontracten op bij een object in uw account. Contracten worden herkend op `referenceId`; ontbreekt die, dan op de combinatie ingangsdatum (`label`) en `unitKey`. Bestaande contracten worden bijgewerkt, nieuwe toegevoegd. Wordt `renters` niet-leeg meegestuurd, dan vervangt dat de bewoners van het contract.\n\n`contracts` mag een lijst zijn, of (legacy) een object met de ingangsdatum als sleutel: `{\"2025-01-01\": {\"amount\": 1200}}`.", "requestBody": { "required": true, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountContractRequest" }, "examples": { "minimal": { "summary": "Minimaal", "value": { "objectKey": "2fqgqz6zqc5hf85irzzqdd3adfa3d", "contracts": [ { "label": "2025-01-01", "amount": 1200 } ] } }, "extended": { "summary": "Uitgebreid", "value": { "objectKey": "2fqgqz6zqc5hf85irzzqdd3adfa3d", "contracts": [ { "label": "2024-01-01", "amount": 1037, "referenceId": "CT-0001", "endDate": null, "unitKey": "kamer-1", "deposit": { "type": "Waarborgsom", "amount": 1800 }, "indexation": [ { "kind": "contract", "ruleId": "cpi-m4", "indexMonth": 7, "endDate": "" } ], "servicekostenAmount": 150, "renters": [ { "firstName": "Jan", "lastNamePrefix": "de", "lastName": "Vries", "email": "jan@example.nl", "mobile": "0612345678" } ] } ] } } } } } }, "responses": { "200": { "description": "Aantal verwerkte en overgeslagen contracten.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/WriteResult" } }, "required": ["result"] }, "example": { "result": { "objectKey": "2fqgqz6zqc5hf85irzzqdd3adfa3d", "written": 1, "skipped": 0 } } } } }, "default": { "description": "Fout. Statuscode blijft 200; controleer `error` in de body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/account-wws-reports": { "post": { "tags": ["Account"], "operationId": "listAccountWwsReports", "summary": "Objecten met een WWS-rapport in uw account", "description": "Geeft alle objecten in het account van `account.email` terug waarvoor een WWS-rapport (type `concept`, `lock` of `current`) bestaat, met de datum van het eerste en het laatste rapport. Meest recent gewijzigd eerst.", "requestBody": { "required": true, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountRequest" }, "examples": { "default": { "value": { "account": { "email": "info@example.nl" } } } } } } }, "responses": { "200": { "description": "Lijst van objecten.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/AccountWwsReportsResult" } }, "required": ["result"] }, "example": { "result": { "status": "ok", "count": 1, "addresses": [ { "objectKey": "2fqgqz6zqc5hf85irzzqdd3adfa3d", "poId": "0599010000137400", "referenceId": "PROP-11928", "firstCreated": "2025-03-01 10:12:00", "lastModified": "2026-02-11 09:40:12" } ] } } } } }, "default": { "description": "Fout. Statuscode blijft 200; controleer `error` in de body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/account-wws-import": { "post": { "tags": ["Account"], "operationId": "importAccountWwsScorings", "summary": "Bestaande WWS-puntentellingen importeren", "description": "Importeert puntentellingen uit een extern systeem als `current` rapport bij een object in uw account. Elke scoring wordt herkend op `externalId`; bestaande worden bijgewerkt. De telling wordt opgeslagen volgens het vastgoed.ai WWS-schema (versie 2) met `document.source` als herkomst.", "requestBody": { "required": true, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountWwsImportRequest" }, "examples": { "default": { "value": { "objectKey": "2fqgqz6zqc5hf85irzzqdd3adfa3d", "scorings": [ { "externalId": "1", "reference": "PZW-00001", "periodId": "2025", "periodStartDate": "2025-01-01", "periodLabel": "1 januari 2025 t/m 30 juni 2025", "totalPoints": 207, "maximumRent": 1254.98, "homeType": "zelfstandig", "isHistorical": false, "breakdown": { "climatePoints": 10, "kitchenPoints": 7, "sanitaryPoints": 8, "parkingPoints": 0, "wozPoints": 46.5 }, "properties": { "wozAmount": 416000, "energyLabel": "A", "kitchens": 1, "sanitaries": 1, "toiletCount": 1, "sinkCount": 1, "extraHeatedRooms": 0 } } ] } } } } } }, "responses": { "200": { "description": "Aantal verwerkte en overgeslagen scorings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/WriteResult" } }, "required": ["result"] }, "example": { "result": { "objectKey": "2fqgqz6zqc5hf85irzzqdd3adfa3d", "written": 1, "skipped": 0 } } } } }, "default": { "description": "Fout. Statuscode blijft 200; controleer `error` in de body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/floorplan": { "post": { "tags": ["Plattegrond"], "operationId": "extractFloorplan", "summary": "Ruimten en oppervlakten uit een plattegrond (Floorplanner.com, Revit/AutoCAD .dwg)", "x-availability": "on-request", "description": "Betaalde uitbreiding, per API-key te activeren. Zolang het endpoint niet is geactiveerd geeft de API foutcode 90 met in `error.activation` de URL om activatie en tarief aan te vragen (https://vastgoed.ai/register#invite=api). \n\nLeest een plattegrond uit en geeft per verdieping de ruimten terug met label, type (vertrek, overige ruimte, verkeersruimte, buitenruimte), oppervlakte in m2 en polygoon, plus de totalen volgens NEN 2580: GO (gebruiksoppervlakte), BVO (bruto vloeroppervlakte) en GBO (gebouwgebonden buitenruimte), en de WWS-oppervlakten (vertrekken, overige ruimten, buitenruimte). Bronnen: een floorplanner.com-project (URL), of een `.dwg`/`.dxf` uit AutoCAD of Revit (exporteer uit Revit naar DWG; ruimtelabels en -oppervlakten op de `A-AREA-*`-lagen worden herkend). Met `bagId`/adres en `wws: true` komt direct een WWS-telling met deze oppervlakten mee, in dezelfde structuur als `/wws-report`.", "requestBody": { "required": true, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FloorplanRequest" }, "examples": { "floorplanner": { "summary": "Floorplanner-project", "value": { "floorplannerUrl": "https://floorplanner.com/projects/174796333/viewer", "bagId": "0599010000137400", "wws": true } }, "dwg": { "summary": "Revit/AutoCAD DWG via tijdelijke URL", "value": { "fileUrl": "https://example.com/tmp/verdieping-1.dwg", "unit": "mm" } } } } } }, "responses": { "200": { "description": "Ruimten, oppervlakten en totalen per verdieping.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/FloorplanResult" } }, "required": ["result"] }, "example": { "result": { "status": "ok", "source": "floorplanner", "floors": [ { "name": "Begane grond", "rooms": [ { "label": "Woonkamer", "type": "vertrek", "areaM2": 28.4 }, { "label": "Keuken", "type": "vertrek", "areaM2": 9.1 }, { "label": "Slaapkamer 1", "type": "vertrek", "areaM2": 14.2 }, { "label": "Hal", "type": "verkeersruimte", "areaM2": 5.3 }, { "label": "Berging", "type": "overige ruimte", "areaM2": 3.8 }, { "label": "Balkon", "type": "buitenruimte", "areaM2": 6.0 } ], "totals": { "go": 60.8, "bvo": 71.2, "gbo": 6.0, "wwsRooms": 51.7, "wwsOtherRooms": 3.8, "wwsOutside": 6.0 } } ], "totals": { "go": 60.8, "bvo": 71.2, "gbo": 6.0, "wwsRooms": 51.7, "wwsOtherRooms": 3.8, "wwsOutside": 6.0 }, "warnings": [] } } } } }, "default": { "description": "Fout. Statuscode blijft 200; controleer `error` in de body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/building": { "post": { "tags": ["Pand"], "operationId": "getBuilding", "summary": "Pandgegevens met alle verblijfsobjecten", "x-availability": "on-request", "description": "Betaalde uitbreiding, per API-key te activeren. Zolang het endpoint niet is geactiveerd geeft de API foutcode 90 met in `error.activation` de URL om activatie en tarief aan te vragen (https://vastgoed.ai/register#invite=api). \n\nGeeft het pand (BAG-pand) terug waar een adres in ligt: pand-id, titel, bouwjaar, gebouwtype, monumentstatus, aantal verblijfsobjecten, en de lijst verblijfsobjecten met adres, `bagId`, gebruiksdoel en gebruiksoppervlakte, gesorteerd op huisnummer en toevoeging. Maximaal 20 objecten per aanroep met `total` en `offset` voor de rest. Bedoeld om een portefeuille per pand op te bouwen, toevoegingen te vinden of een VvE in kaart te brengen. Zelfde identifiers als `/object`.", "requestBody": { "required": true, "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectLookupRequest" }, "examples": { "bagId": { "summary": "Op bagId", "value": { "bagId": "0599010000137400" } }, "postcode": { "summary": "Op postcode en huisnummer", "value": { "postcode": "3013CB", "housenr": 17, "housenraddition": "C" } }, "street": { "summary": "Op straat, huisnummer en plaats", "value": { "streetname": "Weena", "housenr": 17, "housenraddition": "C", "city": "Rotterdam" } } } } } }, "responses": { "200": { "description": "Pand en verblijfsobjecten.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/BuildingResult" } }, "required": ["result"] }, "example": { "result": { "status": "ok", "building": { "bagId": "0363100012119877", "title": "Jan Evertsenstraat 83-85, Amsterdam", "buildYear": 1927, "type": "flatwoning (overig)", "monument": { "type": "gemeentemonument", "id": "00000001002564440000" }, "objectsCount": 9 }, "objects": [ { "bagId": "0363010000684318", "title": "Jan Evertsenstraat 85-1, Amsterdam", "housenr": 85, "housenraddition": "1", "postcode": "1057BS", "bagType": "residential", "bagM2": 52 } ], "total": 9, "offset": 0, "limit": 20 } } } } }, "default": { "description": "Fout. Statuscode blijft 200; controleer `error` in de body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "Uw API-key in de header `X-Api-Key`. Alternatief: `apiKey` in de JSON-body, of in de JSON van de queryparameter `json` bij `GET`. Geen key? Vraag een gratis proefsleutel aan met `POST /v1/trial`, of registreer via https://vastgoed.ai/register#invite=api voor een betaalde key." } }, "schemas": { "ObjectLookupRequest": { "type": "object", "properties": { "bagId": { "type": "string", "description": "BAG verblijfsobject-id (16 cijfers, met voorloopnul). Alias: `poId`.", "examples": ["0599010000137400"], "pattern": "^[0-9]{16}$" }, "poId": { "type": "string", "description": "Alias van `bagId`.", "examples": ["0599010000137400"] }, "objectKey": { "type": "string", "description": "vastgoed.ai objectsleutel van een object in uw account (retour van `/account-object`).", "examples": ["2fqgqz6zqc5hf85irzzqdd3adfa3d"] }, "referenceId": { "type": "string", "description": "Uw eigen referentie zoals eerder via `/account-object` (`reference`) opgeslagen. Hoofdletterongevoelig.", "examples": ["PROP-11928"] }, "postcode": { "type": "string", "description": "Postcode, met of zonder spatie. Combineren met `housenr` (en optioneel `housenraddition`).", "examples": ["3013CB", "3013 CB"] }, "streetname": { "type": "string", "description": "Straatnaam, hoofdletterongevoelig. Combineren met `housenr` en `city` (en optioneel `housenraddition`).", "examples": ["Weena"] }, "housenr": { "type": ["integer", "string"], "description": "Huisnummer zonder toevoeging.", "examples": [17] }, "housenraddition": { "type": "string", "description": "Huisnummertoevoeging. Een voorloopspatie of -streepje wordt genegeerd (`-C`, `C` en `c` zijn gelijk).", "examples": ["C"] }, "city": { "type": "string", "description": "Plaatsnaam, alleen bij zoeken op `streetname`. `Den Haag` en `'s-Gravenhage` worden beide herkend.", "examples": ["Rotterdam"] }, "energyLabelHistory": { "type": "boolean", "default": false, "description": "Met `true` komt in `energyLabel.history` de labelhistorie van het adres mee: alle eerder in EP-online geregistreerde en inmiddels vervangen of vervallen energielabels, die EP-online zelf niet meer teruggeeft. Opgebouwd uit onze maandelijkse EP-online-peilingen sinds 2022. Betaalde uitbreiding, per API-key te activeren. Zolang de optie niet is geactiveerd geeft de API foutcode 90 met in `error.activation` de URL om activatie en tarief aan te vragen (https://vastgoed.ai/register#invite=api).", "examples": [true] } }, "description": "Een object wordt gevonden op precies een van deze manieren, in deze volgorde van voorrang: `objectKey`, `referenceId`, `bagId`/`poId`, `postcode + housenr (+ housenraddition)`, `streetname + housenr (+ housenraddition) + city`. Levert een adres meerdere objecten op (bijvoorbeeld 17-A t/m 17-D zonder toevoeging), dan volgt fout 74 met de kandidaten. Bestaat de opgegeven toevoeging niet op dat huisnummer (bijvoorbeeld `Hs` waar de BAG `H` kent), dan fout 76 met alle objecten op dat huisnummer als kandidaten; er wordt nooit stilzwijgend een ander object gekozen. Levert het adres niets op, dan fout 75. Kandidaten zijn gesorteerd op toevoeging, maximaal 20." }, "WwsEstimateRequest": { "type": "object", "properties": { "bagId": { "type": "string", "description": "BAG verblijfsobject-id (16 cijfers, met voorloopnul). Alias: `poId`.", "examples": ["0599010000137400"], "pattern": "^[0-9]{16}$" }, "poId": { "type": "string", "description": "Alias van `bagId`.", "examples": ["0599010000137400"] }, "objectKey": { "type": "string", "description": "vastgoed.ai objectsleutel van een object in uw account (retour van `/account-object`).", "examples": ["2fqgqz6zqc5hf85irzzqdd3adfa3d"] }, "referenceId": { "type": "string", "description": "Uw eigen referentie zoals eerder via `/account-object` (`reference`) opgeslagen. Hoofdletterongevoelig.", "examples": ["PROP-11928"] }, "postcode": { "type": "string", "description": "Postcode, met of zonder spatie. Combineren met `housenr` (en optioneel `housenraddition`).", "examples": ["3013CB", "3013 CB"] }, "streetname": { "type": "string", "description": "Straatnaam, hoofdletterongevoelig. Combineren met `housenr` en `city` (en optioneel `housenraddition`).", "examples": ["Weena"] }, "housenr": { "type": ["integer", "string"], "description": "Huisnummer zonder toevoeging.", "examples": [17] }, "housenraddition": { "type": "string", "description": "Huisnummertoevoeging. Een voorloopspatie of -streepje wordt genegeerd (`-C`, `C` en `c` zijn gelijk).", "examples": ["C"] }, "city": { "type": "string", "description": "Plaatsnaam, alleen bij zoeken op `streetname`. `Den Haag` en `'s-Gravenhage` worden beide herkend.", "examples": ["Rotterdam"] }, "properties": { "type": "object", "properties": { "measuredM2": { "type": "number", "description": "Gemeten oppervlakte vertrekken in m2; vervangt de BAG-oppervlakte in de schatting.", "examples": [90] }, "outsideMeasuredM2": { "type": "number", "description": "Gemeten buitenruimte in m2.", "examples": [8] } } }, "output": { "type": "string", "description": "`json` (standaard) geeft het rapport gefilterd op de gedocumenteerde sleutels; `raw` geeft het volledige interne rapport.", "enum": ["json", "raw"], "default": "json" } }, "description": "Een object wordt gevonden op precies een van deze manieren, in deze volgorde van voorrang: `objectKey`, `referenceId`, `bagId`/`poId`, `postcode + housenr (+ housenraddition)`, `streetname + housenr (+ housenraddition) + city`. Levert een adres meerdere objecten op (bijvoorbeeld 17-A t/m 17-D zonder toevoeging), dan volgt fout 74 met de kandidaten. Bestaat de opgegeven toevoeging niet op dat huisnummer (bijvoorbeeld `Hs` waar de BAG `H` kent), dan fout 76 met alle objecten op dat huisnummer als kandidaten; er wordt nooit stilzwijgend een ander object gekozen. Levert het adres niets op, dan fout 75. Kandidaten zijn gesorteerd op toevoeging, maximaal 20." }, "WwsReportRequest": { "type": "object", "properties": { "objectKey": { "type": "string", "description": "vastgoed.ai objectsleutel van een object in uw account (retour van `/account-object`).", "examples": ["2fqgqz6zqc5hf85irzzqdd3adfa3d"] }, "referenceId": { "type": "string", "description": "Uw eigen referentie zoals eerder via `/account-object` (`reference`) opgeslagen. Hoofdletterongevoelig.", "examples": ["PROP-11928"] }, "type": { "type": "string", "description": "Filter op rapporttype. Standaard `lock` en `concept`.", "enum": ["lock"] }, "wwsId": { "type": "string", "description": "Specifieke rapportrevisie." }, "unitKey": { "type": "string", "description": "Eenheid (kamer) bij een onzelfstandig object; de `reference` waarmee de eenheid via `/account-object` is aangemaakt.", "examples": ["kamer-1"] }, "properties": { "allOf": [ { "$ref": "#/components/schemas/WwsProperties" } ], "description": "WWS-kenmerken voor een live telling. Zie `WwsProperties`." }, "output": { "type": "string", "description": "`json` (standaard) geeft het rapport gefilterd op de gedocumenteerde sleutels; `raw` geeft het volledige interne rapport.", "enum": ["json", "raw"], "default": "json" } } }, "AccountObjectRequest": { "type": "object", "properties": { "bagId": { "type": "string", "description": "BAG verblijfsobject-id (16 cijfers, met voorloopnul). Alias: `poId`.", "examples": ["0599010000137400"], "pattern": "^[0-9]{16}$" }, "objectKey": { "type": "string", "description": "Bestaand object bijwerken." }, "postcode": { "type": "string", "description": "Postcode, met of zonder spatie. Combineren met `housenr` (en optioneel `housenraddition`).", "examples": ["3013CB", "3013 CB"] }, "streetname": { "type": "string", "description": "Straatnaam, hoofdletterongevoelig. Combineren met `housenr` en `city` (en optioneel `housenraddition`).", "examples": ["Weena"] }, "housenr": { "type": ["integer", "string"], "description": "Huisnummer zonder toevoeging.", "examples": [17] }, "housenraddition": { "type": "string", "description": "Huisnummertoevoeging. Een voorloopspatie of -streepje wordt genegeerd (`-C`, `C` en `c` zijn gelijk).", "examples": ["C"] }, "city": { "type": "string", "description": "Plaatsnaam, alleen bij zoeken op `streetname`. `Den Haag` en `'s-Gravenhage` worden beide herkend.", "examples": ["Rotterdam"] }, "account": { "$ref": "#/components/schemas/Account" }, "reference": { "type": "string", "description": "Uw eigen object-id; wordt opgeslagen en is daarna bruikbaar als `referenceId`. Bij `type: \"unit\"` is dit het id van de eenheid.", "examples": ["PROP-11928"] }, "owner": { "type": "string", "description": "Eigenaar-id of -naam binnen uw systeem.", "examples": ["Midvast BV"] }, "type": { "type": "string", "description": "`unit` om een onzelfstandige eenheid (kamer) toe te voegen.", "enum": ["unit"] }, "label": { "type": "string", "description": "Label van de eenheid, alleen bij `type: \"unit\"`.", "examples": ["Kamer 1"] }, "properties": { "type": "object", "properties": { "measuredM2": { "type": "number", "description": "Gemeten oppervlakte vertrekken in m2.", "examples": [60] }, "outsideMeasuredM2": { "type": "number", "description": "Gemeten buitenruimte in m2.", "examples": [4] } } } } }, "Account": { "type": "object", "properties": { "email": { "type": "string", "description": "E-mailadres van een gebruiker in het vastgoed.ai account.", "format": "email", "examples": ["info@example.nl"] } }, "required": ["email"] }, "AccountRequest": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/Account" } }, "required": ["account"] }, "Contract": { "type": "object", "properties": { "label": { "type": "string", "description": "Ingangsdatum (ISO 8601).", "format": "date", "examples": ["2025-01-01"] }, "amount": { "type": "number", "description": "Kale huur per maand in euro op de ingangsdatum.", "examples": [1200] }, "referenceId": { "type": "string", "description": "Uw contract-id, primaire sleutel bij bijwerken.", "examples": ["CT-0001"] }, "endDate": { "type": ["string", "null"], "format": "date" }, "unitKey": { "type": "string", "description": "Eenheid (kamer) bij een onzelfstandig object.", "examples": ["kamer-1"] }, "deposit": { "type": "object", "properties": { "type": { "type": "string", "examples": ["Waarborgsom"] }, "amount": { "type": "number", "examples": [1800] } } }, "indexation": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "examples": ["contract"] }, "ruleId": { "type": "string", "description": "Indexatieregel, bijvoorbeeld `cpi-m4`.", "examples": ["cpi-m4"] }, "indexMonth": { "type": "integer", "description": "Maand van indexatie (1-12).", "examples": [7] }, "endDate": { "type": ["string", "null"] } } } }, "servicekostenAmount": { "type": "number", "description": "Servicekosten per maand in euro.", "examples": [150] }, "renters": { "type": "array", "items": { "type": "object", "properties": { "firstName": { "type": "string" }, "lastNamePrefix": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string", "format": "email" }, "mobile": { "type": "string" } } } } }, "required": ["label", "amount"] }, "AccountContractRequest": { "type": "object", "properties": { "objectKey": { "type": "string", "description": "vastgoed.ai objectsleutel van een object in uw account (retour van `/account-object`).", "examples": ["2fqgqz6zqc5hf85irzzqdd3adfa3d"] }, "contracts": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/Contract" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Contract" }, "description": "Legacy: ingangsdatum als sleutel." } ] } }, "required": ["objectKey", "contracts"] }, "AccountWwsImportRequest": { "type": "object", "properties": { "objectKey": { "type": "string", "description": "vastgoed.ai objectsleutel van een object in uw account (retour van `/account-object`).", "examples": ["2fqgqz6zqc5hf85irzzqdd3adfa3d"] }, "scorings": { "type": "array", "items": { "type": "object", "properties": { "externalId": { "type": "string", "description": "Primaire sleutel van de scoring in uw systeem.", "examples": ["1"] }, "reference": { "type": "string", "examples": ["PZW-00001"] }, "periodId": { "type": "string", "description": "WWS-periode.", "examples": ["2025", "middenhuur", "2024"] }, "periodStartDate": { "type": "string", "format": "date" }, "periodLabel": { "type": "string" }, "totalPoints": { "type": "number" }, "maximumRent": { "type": "number" }, "homeType": { "type": "string", "enum": ["zelfstandig", "onzelfstandig"] }, "isHistorical": { "type": "boolean" }, "breakdown": { "type": "object", "properties": { "climatePoints": { "type": "number" }, "kitchenPoints": { "type": "number" }, "sanitaryPoints": { "type": "number" }, "parkingPoints": { "type": "number" }, "wozPoints": { "type": "number" }, "segments": { "type": "array", "items": { "type": "object" }, "description": "Gestructureerde rubrieken (v2)." }, "pointResults": { "type": "array", "items": { "type": "object" }, "description": "Regelniveau (v1)." } } }, "properties": { "type": "object", "properties": { "wozAmount": { "type": "number" }, "energyLabel": { "type": "string" }, "kitchens": { "type": "integer" }, "sanitaries": { "type": "integer" }, "toiletCount": { "type": "integer" }, "sinkCount": { "type": "integer" }, "extraHeatedRooms": { "type": "integer" } }, "additionalProperties": true } }, "required": ["externalId"] } } }, "required": ["objectKey", "scorings"] }, "Address": { "type": "object", "properties": { "streetname": { "type": "string", "examples": ["Weena"] }, "housenr": { "type": "integer", "examples": [17] }, "housenraddition": { "type": ["string", "null"], "examples": ["C"] }, "city": { "type": "string", "examples": ["Rotterdam"] }, "postcode": { "type": "string", "examples": ["3013CB"] }, "country": { "type": "string", "examples": ["nl"] }, "slugKey": { "type": "string", "description": "Stabiele leesbare adressleutel, bruikbaar in URL's.", "examples": ["rotterdam-weena-ivapma"] } } }, "WozValue": { "type": "object", "properties": { "year": { "type": "integer", "description": "Belastingjaar.", "examples": [2026] }, "snapshot": { "type": "string", "description": "Waardepeildatum (1 januari van het jaar ervoor).", "format": "date", "examples": ["2025-01-01"] }, "value": { "type": "integer", "description": "WOZ-waarde in euro.", "examples": [416000] } } }, "EnergyLabelHistoryItem": { "type": "object", "properties": { "letter": { "type": "string", "description": "Labelletter van het eerdere label (`A++++` t/m `G`).", "examples": ["F"] }, "index": { "type": ["number", "boolean"], "description": "Energie-index bij labels uit 2015-2020; `false` als niet van toepassing.", "examples": [1.85] }, "registration": { "type": "string", "format": "date", "description": "Registratiedatum in EP-online.", "examples": ["2017-11-09"] }, "expire": { "type": "string", "format": "date", "description": "Oorspronkelijke geldigheid (tien jaar na opname).", "examples": ["2027-11-09"] }, "replaced": { "type": "string", "format": "date", "description": "Maand waarin het label in EP-online is vervangen door een nieuw label of is vervallen (eerste dag van de maand; maandnauwkeurig, afgeleid uit onze maandelijkse peilingen).", "examples": ["2025-11-01"] } }, "description": "Een eerder geregistreerd energielabel van het adres dat inmiddels in EP-online is vervangen of vervallen." }, "ObjectResult": { "type": "object", "properties": { "status": { "type": "string", "description": "`ok`, of `error` als het object wel gevonden is maar er geen rapport kon worden gemaakt (zie `error`).", "enum": ["ok", "error"] }, "bagId": { "type": "string", "description": "BAG verblijfsobject-id (16 cijfers). De unieke sleutel van de woning; bewaar deze voor vervolgcalls.", "examples": ["0599010000137400"] }, "title": { "type": "string", "description": "Leesbare titel: straat, huisnummer met toevoeging, plaats.", "examples": ["Weena 17-C, Rotterdam"] }, "address": { "$ref": "#/components/schemas/Address" }, "properties": { "type": "object", "properties": { "bagType": { "type": "string", "description": "Gebruiksdoel volgens de BAG, samengevat: `residential` (woonfunctie), `commercial` (winkel, kantoor, bijeenkomst, industrie) of `other`. Alleen `residential` krijgt een WWS-telling.", "enum": ["residential", "commercial", "other"], "examples": ["residential"] }, "bagM2": { "type": "integer", "description": "Gebruiksoppervlakte in m2 volgens de BAG (geen WWS-oppervlakte; de WWS telt alleen vertrekken en overige ruimten). Zonder opname is dit de basis voor de puntenschatting.", "examples": [79] } }, "description": "Basiskenmerken van het verblijfsobject uit de BAG." }, "latlng": { "type": "object", "properties": { "lat": { "type": "number", "examples": [51.92499746298337] }, "lng": { "type": "number", "examples": [4.476839361191538] } }, "description": "WGS84-coördinaat van het verblijfsobject (BAG-geometrie, omgerekend uit RD)." }, "energyLabel": { "type": "object", "properties": { "letter": { "type": ["string", "boolean"], "description": "Geregistreerde labelletter uit EP-online (`A++++` t/m `G`), `false` als er geen label is geregistreerd.", "examples": ["A"] }, "index": { "type": ["number", "boolean"], "description": "Energie-index van labels uit 2015-2020 (oude methodiek); `false` als niet van toepassing. Voor de WWS telt bij die labels de index, niet de letter." }, "registration": { "type": ["string", "boolean"], "format": "date", "description": "Registratiedatum in EP-online; `false` als er geen label is.", "examples": ["2025-04-29"] }, "expire": { "type": ["string", "boolean"], "format": "date", "description": "Geldig tot (tien jaar na opname). Een verlopen label telt niet mee in de WWS; kijk voor de WWS-geldigheid naar `report.energyLabel.valid` in `/wws-estimate`.", "examples": ["2035-04-10"] }, "history": { "type": "array", "description": "Alleen met `energyLabelHistory: true` (betaalde uitbreiding). Eerder geregistreerde energielabels van dit adres, nieuwste eerst; het huidige label staat er niet in. EP-online toont alleen het huidige label; deze historie komt uit onze eigen maandelijkse peilingen van EP-online sinds 2022. Leeg (`[]`) als er in die periode geen eerder label bekend is.", "items": { "$ref": "#/components/schemas/EnergyLabelHistoryItem" } } }, "description": "Energielabel zoals geregistreerd in EP-online (RVO). Dit is het geregistreerde label; of het label ook geldig is voor de WWS staat in het rapport van `/wws-estimate`. Met `energyLabelHistory: true` (betaalde uitbreiding) komt in `history` ook de labelhistorie mee." }, "monument": { "type": ["object", "array"], "description": "Monumentstatus van het pand: `{type, id}` met `type` `rijksmonument`, `gemeentemonument` of `beschermdgezicht` (rijksbeschermd stads- of dorpsgezicht) en `id` het registratienummer (Rijksdienst voor het Cultureel Erfgoed of het gemeentelijke register). Leeg (`[]`) als het pand geen monument is. Een monument geeft een huurprijsopslag in de WWS.", "properties": { "type": { "type": "string", "enum": ["rijksmonument", "gemeentemonument", "beschermdgezicht"] }, "id": { "type": "string", "examples": ["00000001002564440000"] } }, "examples": [ { "type": "gemeentemonument", "id": "00000001002564440000" }, [] ] }, "ownership": { "type": ["object", "array"], "description": "Eigendomsinformatie uit het Kadaster op de locatie van het object, per type: `corporatie` (naam van de woningcorporatie die eigenaar is) en/of `erfpacht` (erfverpachter, bijvoorbeeld `Gemeente Amsterdam`). Leeg (`[]`) als geen van beide bekend is.", "properties": { "corporatie": { "type": "string", "examples": ["3B-Wonen"] }, "erfpacht": { "type": "string", "examples": ["Gemeente Amsterdam"] } }, "examples": [ { "erfpacht": "Gemeente Amsterdam" }, [] ] }, "woz": { "type": "array", "items": { "$ref": "#/components/schemas/WozValue" }, "description": "WOZ-waarden uit het WOZ-waardeloket per belastingjaar, meest recente eerst (doorgaans vanaf belastingjaar 2020). `year` is het belastingjaar, `snapshot` de waardepeildatum (1 januari van het jaar ervoor). De meest recente waarde bepaalt de WOZ-punten in de WWS." } }, "description": "Alle openbare woningobjectgegevens van een adres: BAG (adres, gebruiksdoel, oppervlakte, coördinaat), energielabel (EP-online), WOZ-historie (WOZ-waardeloket), monumentstatus (RCE en gemeenten) en eigendom (Kadaster). De bronnen zijn per adres gekoppeld en worden doorlopend bijgewerkt." }, "Report": { "type": "object", "properties": { "settings": { "type": "object", "properties": { "generated": { "type": "integer", "description": "Unix timestamp van de berekening.", "examples": [1787121550] }, "period": { "type": "string", "description": "WWS-periode (beleidsjaar).", "examples": ["2026"] }, "year": { "type": "integer", "examples": [2026] } } }, "points": { "type": "object", "properties": { "rooms": { "type": "number", "description": "Vertrekken." }, "otherRooms": { "type": "number", "description": "Overige ruimten." }, "climate": { "type": "number", "description": "Verwarming en koeling." }, "energyLabel": { "type": "number" }, "kitchen": { "type": "number" }, "sanitary": { "type": "number" }, "outside": { "type": "number", "description": "Buitenruimte." }, "parking": { "type": "number" }, "sharedRooms": { "type": "number", "description": "Gedeelde ruimten (onzelfstandig)." }, "woz": { "type": "number" }, "label": { "type": "string", "examples": ["184 pt - 197 pt", "128 pt"] }, "range": { "type": "object", "properties": { "min": { "type": "number", "examples": [184] }, "max": { "type": "number", "examples": [197] } }, "description": "Alleen bij een schatting (`/wws-estimate`): ondergrens en bovengrens. Een vastgesteld rapport (`/wws-report`) heeft geen `range`; het totaal staat in `label`." } } }, "energyLabel": { "type": "object", "properties": { "label": { "type": "string", "examples": ["Energielabel A"] }, "valid": { "type": "boolean", "description": "Of het label nog geldig is op de peildatum." }, "derived": { "type": "object", "properties": { "registration": { "type": ["string", "boolean"], "format": "date", "description": "Registratiedatum, `false` als er geen geldig label is." }, "expire": { "type": ["string", "boolean"], "format": "date" }, "notice": { "type": ["string", "boolean"], "description": "Waarom het label niet (volledig) meetelt, bijvoorbeeld `Geen vereiste energie-index.` (label 2015-2020 zonder index), `Energielabel verlopen op ...`, `Geen geregistreerd energielabel.`, of `Vervalt binnenkort.`; `false` als er niets te melden is.", "examples": ["Geen vereiste energie-index."] } } } } }, "woz": { "type": "object", "properties": { "label": { "type": "string", "examples": ["€ 416.000"] }, "amount": { "type": "integer", "examples": [416000] }, "derived": { "type": "object", "properties": { "date": { "type": "string", "examples": ["Peildatum 2025-01-01"] }, "label": { "type": "string" }, "calculation": { "type": "string", "description": "Toegepaste WOZ-puntenformule.", "examples": ["(416000 / 16954) + (416000 / 71 / 268)"] } } } } }, "sector": { "type": "object", "properties": { "regulated": { "type": "boolean", "description": "Of het object (mogelijk) onder de gereguleerde huur valt." }, "label": { "type": "string", "examples": ["Middenhuursegment of vrijehuursector", "sociale huur"] }, "ids": { "type": "array", "items": { "type": "string", "enum": ["LOW", "MIDDLE", "HIGH"] }, "description": "Bij een schatting: mogelijke segmenten binnen de puntenrange, van min naar max. LOW = sociaal, MIDDLE = middenhuur, HIGH = vrije sector." }, "likely": { "type": "string", "description": "Bij een schatting: het segment waar het grootste deel van de puntenrange in valt.", "enum": ["LOW", "MIDDLE", "HIGH"] }, "id": { "type": "string", "description": "Bij een vastgesteld rapport: het segment.", "enum": ["LOW", "MIDDLE", "HIGH"] } } }, "building": { "type": "object", "properties": { "monument": { "type": ["boolean", "string"], "description": "Monumenttype (`rijksmonument`, `gemeentemonument`, `beschermdgezicht`) of `false`.", "examples": ["gemeentemonument"] }, "buildYear": { "type": ["integer", "null"], "examples": [1984] } } }, "price": { "type": "object", "properties": { "label": { "type": "string", "examples": ["€ 1.214,31 - markthuur", "€ 829,94"] }, "derived": { "type": "object", "properties": { "percentalIncrease": { "type": "number", "description": "Toegepaste huurprijsopslag als fractie: 0.35 rijksmonument, 0.15 gemeentemonument, 0.05 beschermd stads- of dorpsgezicht (bouwjaar voor 1965), anders 0.", "examples": [0.15] }, "amount": { "type": "number", "description": "Bij een vastgesteld rapport: maximale huurprijs." } } }, "range": { "type": "object", "properties": { "min": { "type": "number", "examples": [1214.31] }, "max": { "type": "number", "examples": [1303.57] } }, "description": "Bij een schatting: maximale huurprijs bij de puntenrange. Boven de liberalisatiegrens geldt de markthuur; dan is dit de markthuurindicatie." }, "amount": { "type": "number", "description": "Bij een vastgesteld rapport: maximale huurprijs per maand.", "examples": [829.94] } } }, "confidence": { "type": "object", "properties": { "sector": { "type": "number", "description": "Zekerheid (0 tot 1) van `sector.likely`: het aandeel van de puntenrange dat in dat segment valt. Valt de hele range in een segment, dan 0.85 / 0.90 / 0.95 naarmate de marge tot de segmentgrens groter is (< 5, < 15, >= 15 punten).", "examples": [0.85] }, "regulation": { "type": "number", "description": "Zekerheid (0 tot 1) van `sector.regulated`. Kruist de range de liberalisatiegrens, dan het aandeel van de range dat gereguleerd is; anders 0.85 / 0.90 / 0.95 op basis van de marge tot die grens.", "examples": [0.15] } }, "description": "Alleen bij een schatting (`/wws-estimate`)." }, "details": { "type": "object", "properties": {}, "description": "Alleen bij een opgeslagen rapport (`/wws-report`): metadata zoals `wwsId` en aanmaakdatum.", "additionalProperties": true }, "pdf": { "type": "string", "description": "Alleen als het object in uw account staat: URL naar het PDF-rapport.", "format": "uri" } }, "description": "Met `output: \"raw\"` bevat het rapport aanvullende sleutels zoals `engineVersion` en `surfaceAreas`." }, "ReportResult": { "type": "object", "properties": { "status": { "type": "string", "description": "`ok`, of `error` als het object wel gevonden is maar er geen rapport kon worden gemaakt (zie `error`).", "enum": ["ok", "error"] }, "bagId": { "type": "string", "description": "BAG verblijfsobject-id (16 cijfers). De unieke sleutel van de woning; bewaar deze voor vervolgcalls.", "examples": ["0599010000137400"] }, "title": { "type": "string", "description": "Leesbare titel: straat, huisnummer met toevoeging, plaats.", "examples": ["Weena 17-C, Rotterdam"] }, "address": { "$ref": "#/components/schemas/Address" }, "properties": { "type": "object", "properties": { "bagType": { "type": "string", "description": "Gebruiksdoel volgens de BAG, samengevat: `residential` (woonfunctie), `commercial` (winkel, kantoor, bijeenkomst, industrie) of `other`. Alleen `residential` krijgt een WWS-telling.", "enum": ["residential", "commercial", "other"], "examples": ["residential"] }, "bagM2": { "type": "integer", "description": "Gebruiksoppervlakte in m2 volgens de BAG (geen WWS-oppervlakte; de WWS telt alleen vertrekken en overige ruimten). Zonder opname is dit de basis voor de puntenschatting.", "examples": [79] } }, "description": "Basiskenmerken van het verblijfsobject uit de BAG." }, "latlng": { "type": "object", "properties": { "lat": { "type": "number", "examples": [51.92499746298337] }, "lng": { "type": "number", "examples": [4.476839361191538] } }, "description": "WGS84-coördinaat van het verblijfsobject (BAG-geometrie, omgerekend uit RD)." }, "report": { "$ref": "#/components/schemas/Report" } } }, "AccountObjectResult": { "type": "object", "properties": { "objectKey": { "type": "string" }, "unitKey": { "type": "string", "description": "Alleen bij `type: \"unit\"`." } }, "required": ["objectKey"] }, "AccountWwsReportsResult": { "type": "object", "properties": { "status": { "type": "string", "enum": ["ok"] }, "count": { "type": "integer" }, "addresses": { "type": "array", "items": { "type": "object", "properties": { "objectKey": { "type": "string" }, "poId": { "type": ["string", "null"] }, "referenceId": { "type": ["string", "null"] }, "firstCreated": { "type": "string", "description": "MySQL datetime, `YYYY-MM-DD HH:MM:SS`.", "examples": ["2025-03-01 10:12:00"] }, "lastModified": { "type": "string", "description": "MySQL datetime, `YYYY-MM-DD HH:MM:SS`.", "examples": ["2026-02-11 09:40:12"] } } } } } }, "WriteResult": { "type": "object", "properties": { "objectKey": { "type": "string" }, "written": { "type": "integer" }, "skipped": { "type": "integer" } } }, "FloorplanRequest": { "type": "object", "properties": { "floorplannerUrl": { "type": "string", "description": "URL van een floorplanner.com-project of -viewer.", "format": "uri", "examples": ["https://floorplanner.com/projects/174796333/viewer"] }, "fileUrl": { "type": "string", "description": "Tijdelijke, direct downloadbare URL naar een `.dwg` of `.dxf` (AutoCAD, of DWG-export uit Revit). Maximaal 50 MB.", "format": "uri" }, "unit": { "type": "string", "description": "Tekeneenheid van het DWG-bestand als die niet uit het bestand blijkt.", "enum": ["mm", "cm", "m"], "default": "mm" }, "bagId": { "type": "string", "description": "BAG verblijfsobject-id (16 cijfers, met voorloopnul). Alias: `poId`.", "examples": ["0599010000137400"], "pattern": "^[0-9]{16}$" }, "postcode": { "type": "string", "description": "Postcode, met of zonder spatie. Combineren met `housenr` (en optioneel `housenraddition`).", "examples": ["3013CB", "3013 CB"] }, "streetname": { "type": "string", "description": "Straatnaam, hoofdletterongevoelig. Combineren met `housenr` en `city` (en optioneel `housenraddition`).", "examples": ["Weena"] }, "housenr": { "type": ["integer", "string"], "description": "Huisnummer zonder toevoeging.", "examples": [17] }, "housenraddition": { "type": "string", "description": "Huisnummertoevoeging. Een voorloopspatie of -streepje wordt genegeerd (`-C`, `C` en `c` zijn gelijk).", "examples": ["C"] }, "city": { "type": "string", "description": "Plaatsnaam, alleen bij zoeken op `streetname`. `Den Haag` en `'s-Gravenhage` worden beide herkend.", "examples": ["Rotterdam"] }, "wws": { "type": "boolean", "description": "Met `true` (en een object-identifier) komt een WWS-telling met deze oppervlakten mee in `result.report`.", "default": false } }, "description": "Geef `floorplannerUrl` of `fileUrl` op. Bestanden worden na verwerking verwijderd." }, "FloorplanRoom": { "type": "object", "properties": { "label": { "type": "string", "description": "Ruimtenaam zoals in de tekening.", "examples": ["Woonkamer"] }, "type": { "type": "string", "description": "WWS-categorie, afgeleid uit het label.", "enum": ["vertrek", "overige ruimte", "verkeersruimte", "buitenruimte", "gedeeld", "onbekend"] }, "areaM2": { "type": "number", "description": "Netto vloeroppervlakte in m2 (binnenzijde wanden).", "examples": [28.4] }, "heated": { "type": ["boolean", "null"], "description": "Verwarmd, als dat uit de bron blijkt; anders `null`." }, "polygon": { "type": "array", "items": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } } }, "description": "Contour in centimeters, oorsprong linksboven van de verdieping." }, "source": { "type": "string", "description": "Herkomst van label en oppervlakte, bijvoorbeeld `floorplanner`, `dwg:A-AREA-IDEN`, `dwg:polygon`." } } }, "FloorplanTotals": { "type": "object", "properties": { "go": { "type": "number", "description": "Gebruiksoppervlakte (NEN 2580) in m2." }, "bvo": { "type": "number", "description": "Bruto vloeroppervlakte in m2." }, "gbo": { "type": "number", "description": "Gebouwgebonden buitenruimte in m2." }, "wwsRooms": { "type": "number", "description": "Som vertrekken in m2." }, "wwsOtherRooms": { "type": "number", "description": "Som overige ruimten in m2." }, "wwsOutside": { "type": "number", "description": "Som buitenruimte in m2." } } }, "FloorplanResult": { "type": "object", "properties": { "status": { "type": "string", "enum": ["ok"] }, "source": { "type": "string", "enum": ["floorplanner", "dwg"] }, "floors": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "examples": ["Begane grond"] }, "rooms": { "type": "array", "items": { "$ref": "#/components/schemas/FloorplanRoom" } }, "totals": { "$ref": "#/components/schemas/FloorplanTotals" } } } }, "totals": { "$ref": "#/components/schemas/FloorplanTotals" }, "report": { "allOf": [ { "$ref": "#/components/schemas/Report" } ], "description": "Alleen met `wws: true` en een object-identifier." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Bijvoorbeeld ruimten zonder oppervlakte, of samengevoegde contouren." } } }, "BuildingResult": { "type": "object", "properties": { "status": { "type": "string", "enum": ["ok"] }, "building": { "type": "object", "properties": { "bagId": { "type": "string", "description": "BAG pand-id." }, "title": { "type": "string" }, "buildYear": { "type": ["integer", "null"] }, "type": { "type": ["string", "null"], "description": "Gebouwtype uit het energielabel." }, "monument": { "type": ["object", "array"] }, "objectsCount": { "type": "integer" } } }, "objects": { "type": "array", "items": { "type": "object", "properties": { "bagId": { "type": "string" }, "title": { "type": "string" }, "housenr": { "type": "integer" }, "housenraddition": { "type": ["string", "null"] }, "postcode": { "type": "string" }, "bagType": { "type": "string", "enum": ["residential", "commercial", "other"] }, "bagM2": { "type": "integer" } } } }, "total": { "type": "integer" }, "offset": { "type": "integer" }, "limit": { "type": "integer" } } }, "Error": { "type": "object", "properties": { "code": { "type": "integer", "description": "Foutcode, zie de tabel in de API-beschrijving.", "examples": [74] }, "message": { "type": "string", "examples": ["Ambiguous address"] }, "devMessage": { "type": "string", "description": "Toelichting voor de ontwikkelaar." }, "activation": { "type": "string", "description": "Alleen bij code 90: URL om activatie en tarief aan te vragen.", "format": "uri" }, "candidates": { "type": "array", "description": "Alleen bij code 74 en 76: de objecten op het opgegeven huisnummer, gesorteerd op toevoeging, maximaal 20.", "items": { "type": "object", "properties": { "bagId": { "type": "string", "examples": ["0599010000131303"] }, "title": { "type": "string", "examples": ["Weena 17-B, Rotterdam"] }, "postcode": { "type": "string", "examples": ["3013CB"] }, "housenraddition": { "type": ["string", "null"], "examples": ["B"] } } } }, "upgrade": { "type": "string", "format": "uri", "description": "Alleen bij code 93, 94 en 95: URL waar de gebruiker zich registreert voor een betaalde API-key." } }, "required": ["code", "message"], "examples": [ { "code": 76, "message": "Unknown housenraddition", "devMessage": "No object found for housenraddition 'Hs'. Pick one of the candidates or use bagId.", "candidates": [ { "bagId": "0599010000159822", "title": "Weena 17-A, Rotterdam", "postcode": "3013CB", "housenraddition": "A" }, { "bagId": "0599010000131303", "title": "Weena 17-B, Rotterdam", "postcode": "3013CB", "housenraddition": "B" }, { "bagId": "0599010000137400", "title": "Weena 17-C, Rotterdam", "postcode": "3013CB", "housenraddition": "C" }, { "bagId": "0599010000232754", "title": "Weena 17-D, Rotterdam", "postcode": "3013CB", "housenraddition": "D" } ] } ] }, "ErrorResponse": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/Error" }, "result": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Bij rapportfouten (78, 79) worden de objectgegevens met `status: \"error\"` meegegeven." }, "trial": { "$ref": "#/components/schemas/TrialUsage" } }, "required": ["error"] }, "WwsProperties": { "type": "object", "properties": { "roomsMeasured": { "type": "array", "description": "List of rooms ('Vertrekken') with their attributes.", "items": { "type": "object", "properties": { "label": { "type": ["string", "null"], "description": "Name or label for the room.", "examples": ["Woonkamer"] }, "value": { "type": ["number", "null"], "description": "Area measurement of the room in square meters.", "examples": [24.33] }, "heated": { "type": ["integer", "null"], "description": "Indicates if the room is heated (1 for yes, 0 for no).", "examples": [1] }, "cooled": { "type": ["integer", "null"], "description": "Indicates if the room is cooled (1 for yes, 0 for no).", "examples": [0] }, "shared": { "type": ["integer", "null"], "description": "Indicates if the room is shared. 0 = not shared, 1 = shared or number of users it is shared with known.", "examples": [0, 1, 6] }, "id": { "type": ["string", "null"], "description": "Unique identifier for the room. Format: 'roomsMeasured-{timestamp}-{index}'. Used by kitchens and sanitaries to reference which room they belong to via inRoom.", "examples": ["roomsMeasured-1773420509-0"] }, "points": { "type": ["number", "null"], "description": "The number of points calculated for this room. Only show if listed.", "examples": [13, 29, 20] } } } }, "openKeuken": { "type": ["boolean", "null"], "description": "(deprecated) Use kitchens[0].openKeuken = 1 and kitchens[0].inRoom = Woonkamer id instead.", "examples": [true], "deprecated": true }, "heatedHallway": { "type": ["integer", "null"], "description": "(deprecated) Instead, add entries under otherRoomsMeasured with a label (e.g. 'Verkeersruimte', 'Hal', 'Overloop'), value 0 and heated 1.", "examples": [0, 1, 2], "deprecated": true }, "otherRoomsMeasured": { "type": "array", "description": "List of other spaces ('Overige ruimte') with their attributes.", "items": { "type": "object", "properties": { "label": { "type": ["string", "null"], "description": "Name or label for the space.", "examples": ["Berging"] }, "value": { "type": ["number", "null"], "description": "Area measurement of the space in square meters.", "examples": [2.3] }, "heated": { "type": ["integer", "null"], "description": "Indicates if the space is heated (1 for yes, 0 for no).", "examples": [0] }, "cooled": { "type": ["integer", "null"], "description": "Indicates if the space is cooled (1 for yes, 0 for no).", "examples": [0] }, "shared": { "type": ["integer", "null"], "description": "Indicates if the space is shared. 0 = not shared, 1 = shared or number of users it is shared with known.", "examples": [0, 1, 6] }, "id": { "type": ["string", "null"], "description": "Unique identifier for the space. Format: 'otherRoomsMeasured-{timestamp}-{index}'. Used by sanitaries to reference which room they belong to via inRoom.", "examples": ["otherRoomsMeasured-1773420509-0"] }, "points": { "type": ["number", "null"], "description": "The number of points calculated for this space. Only show if listed.", "examples": [5, 4, 1] } } } }, "outsideMeasured": { "type": "array", "description": "List of othe outside spaces ('Buitenruimte') with their attributes.", "items": { "type": "object", "properties": { "label": { "type": ["string", "null"], "description": "Name or label for the outside space.", "examples": ["Balkon"] }, "value": { "type": ["number", "null"], "description": "Area measurement of the outside space in square meters.", "examples": [10] }, "shared": { "type": ["integer", "null"], "description": "Indicates if the outside space is shared. 0 = not shared, 1 = shared or number of users it is shared with known.", "examples": [0, 1, 6] }, "points": { "type": ["number", "null"], "description": "The number of points calculated for this space. Only show if listed.", "examples": [15, 5.5, 2.75] } } } }, "noOutsideSpace": { "type": ["boolean", "null"], "description": "Indicates if there are no outside spaces associated with the property.", "examples": [false] }, "kitchens": { "type": "array", "description": "List of kitchen amenities and appliances.", "items": { "type": "object", "properties": { "title": { "type": ["string", "null"], "description": "Title or name for the kitchen configuration.", "examples": ["Main Kitchen"] }, "aanrecht": { "type": ["string", "null"], "enum": ["LangerDanTwee", "TussenEenEnTwee", "Korter"], "description": "Describes the length of the countertop. 'LangerDanTwee' if 2m or longer, 'TussenEenEnTwee' if between 1m and 2m, 'Korter' if shorter than 1m." }, "kookplaat": { "type": ["string", "null"], "enum": ["Geen", "Gas", "Inductie", "Keramisch"], "description": "Type of stove or cooktop present." }, "oven": { "type": ["string", "null"], "enum": ["Geen", "Electrisch", "Gas"], "description": "Type of oven present." }, "koelkast": { "type": ["integer", "null"], "description": "Number of refrigerators present.", "examples": [1] }, "vrieskast": { "type": ["integer", "null"], "description": "Number of freezers available.", "examples": [0] }, "magnetron": { "type": ["integer", "null"], "description": "Number of microwaves available.", "examples": [1] }, "vaatwasmachine": { "type": ["integer", "null"], "description": "Number of dishwashers available.", "examples": [1] }, "afzuiginstallatie": { "type": ["integer", "null"], "description": "Indicates if an extractor hood is present (1 = yes, 0 = no)." }, "kastLos": { "type": ["integer", "null"], "description": "Number of standalone cabinets above the minimum requirement.", "examples": [3] }, "eenhandsMengkraan": { "type": ["integer", "null"], "description": "Number of single lever mixer taps available.", "examples": [1] }, "thermostatischeMengkraan": { "type": ["integer", "null"], "description": "Number of thermostatic mixer taps available.", "examples": [1] }, "kokendwaterfunctie": { "type": ["integer", "null"], "description": "Indicates if a boiling water feature is available (1 = yes, 0 = no)." }, "quality": { "type": ["integer", "null"], "description": "Kitchen quality points. Only set a value when no other amenities and appliances except for aanrecht is supplied." }, "inRoom": { "type": ["string", "null"], "description": "References the id of the room this kitchen belongs to. Required when openKeuken is true, referencing the Woonkamer id.", "examples": ["roomsMeasured-1773420509-0"] } } } }, "sanitaries": { "type": "array", "description": "List of sanitary facilities and fittings.", "items": { "type": "object", "properties": { "title": { "type": ["string", "null"], "description": "Title or label for the sanitary setup.", "examples": ["Main Bathroom"] }, "toilet": { "type": ["string", "null"], "enum": ["Geen", "Seperaat", "SeperaatHangend", "InBadkamer", "InBadkamerHangend"], "description": "Type of toilet facility. For example, 'SeperaatHangend' indicates a wall-mounted toilet in a separate space." }, "badDouche": { "type": ["string", "null"], "enum": ["Geen", "Douche", "Bad", "BadPlusDouche"], "description": "Identifies bathing facility: none, shower, bath, or bath plus separate shower." }, "wastafel": { "type": ["integer", "null"], "description": "Number of washbasins.", "examples": [0, 1, 2] }, "wastafelMulti": { "type": ["integer", "null"], "description": "Number of multi-user washbasins (minimum width and 2 taps).", "examples": [0, 1, 2] }, "bubbelFunctieBad": { "type": ["integer", "null"], "description": "Indicates if the bath has a bubble function (1 = yes, 0 = no)." }, "volledigeAfscheiding": { "type": ["integer", "null"], "description": "Indicates if there is a full separation for the shower (1 = yes, 0 = no)." }, "handdoekRadiator": { "type": ["integer", "null"], "description": "Indicates if there is a towel radiator (1 = yes, 0 = no)." }, "kastWastafel": { "type": ["integer", "null"], "description": "Indicates if there is a cabinet under the washbasin (1 = yes, 0 = no)." }, "kastLos": { "type": ["integer", "null"], "description": "Indicates if there is additional cupboard space (1 = yes, 0 = no)." }, "stopContact": { "type": ["integer", "null"], "description": "Number of electrical outlets in the sanitary area (max 2 per (multi-user) washbasin)." }, "eenhandsMengkraan": { "type": ["integer", "null"], "description": "Number of single lever mixer taps in the sanitary area." }, "thermostatischeMengkraan": { "type": ["integer", "null"], "description": "Number of thermostatic mixer taps in the sanitary area." }, "quality": { "type": ["integer", "null"], "description": "Sanitary quality points. Only set a value when no other facilities and fittings except for toilet, badDouche, wastafel or wastafelMulti are supplied." }, "inRoom": { "type": ["string", "null"], "description": "References the id of the room (from roomsMeasured or otherRoomsMeasured) this sanitary belongs to.", "examples": ["roomsMeasured-1773420509-1"] } } } }, "parkings": { "type": "array", "description": "Details of parking facilities in shared spaces (e.g., parking garage, parking lot). Not for individual parking facilities. This is optional; leave empty if unknown.", "items": { "type": "object", "properties": { "title": { "type": ["string", "null"], "description": "Description or name for the parking setup.", "examples": ["Property parkinglot"] }, "type": { "type": ["string", "null"], "enum": ["Geen", "Buiten", "BuitenOverdekt", "Binnen"], "description": "Type of parking facility: outside, covered outside, or indoors." }, "chargers": { "type": ["integer", "null"], "description": "Number of exclusive charging stations (1 = yes, 0 = no)." } } } }, "videoPhone": { "type": ["boolean", "null"], "description": "Indicates if there is a video intercom system available.", "examples": [false, true] }, "energyLabel": { "type": "object", "description": "Energy efficiency label of the property. Optional; leave empty if unknown.", "properties": { "energielabelLetter": { "type": ["string", "null"], "description": "Energy label letter indicating efficiency.", "examples": ["A+++"] }, "source": { "type": ["string", "null"], "description": "Source of the energy label. If 'energielabelLetter' is provided, this value is 'ai'." } } }, "monument": { "type": "object", "description": "Monumental status of the property. Optional; leave empty if unknown.", "properties": { "type": { "type": ["string", "null"], "enum": ["rijksmonument", "gemeentemonument", "beschermdgezicht"], "description": "Type of monumental designation." }, "id": { "type": ["string", "null"], "description": "Identification number for the monument.", "examples": ["00000004000000080000"] }, "source": { "type": ["string", "null"], "description": "Source of the monument data. If 'type' is defined, this value is 'ai'." } } }, "woz": { "type": "object", "description": "The WOZ value in euro's. Optional. Leave empty if unknown.", "properties": { "value": { "type": ["number", "null"], "description": "The value of the WOZ as a number (e.g. without currency or formatting).", "examples": [100000.0, 234000.0, 1500000.0] } } } }, "description": "WWS-kenmerken van de woning. Alle velden zijn optioneel; ontbrekende kenmerken worden uit openbare data aangevuld of tellen niet mee. Gelijk aan het vastgoed.ai WWS-schema (versie 2)." }, "TrialRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Optioneel. E-mailadres van de gebruiker. Met e-mailadres dekt de proefsleutel 20 unieke adressen, zonder 5. Hetzelfde e-mailadres levert steeds dezelfde sleutel op. Gebruik alleen een echt adres van de gebruiker, geen placeholder.", "examples": ["naam@bedrijf.nl"] } } }, "TrialResult": { "type": "object", "properties": { "status": { "type": "string", "enum": ["ok"] }, "apiKey": { "type": "string", "description": "De proefsleutel; meesturen als header `X-Api-Key`.", "examples": ["trial_36173b1bc47fa7c45d05"] }, "type": { "type": "string", "enum": ["trial"] }, "email": { "type": ["string", "boolean"], "description": "Het geregistreerde e-mailadres, of `false` bij een anonieme sleutel." }, "addressLimit": { "type": "integer", "description": "Aantal unieke adressen dat de sleutel dekt (5 anoniem, 20 met e-mailadres).", "examples": [20] }, "addressesUsed": { "type": "integer", "examples": [0] }, "addressesRemaining": { "type": "integer", "examples": [20] }, "endpoints": { "type": "array", "items": { "type": "string" }, "description": "Endpoints die de proefsleutel ondersteunt.", "examples": [ ["/object", "/wws-estimate"] ] }, "upgrade": { "type": "string", "format": "uri", "description": "Registratie-URL voor een betaalde API-key." }, "devMessage": { "type": "string", "description": "Instructies voor de aanroepende agent." } }, "required": ["status", "apiKey", "addressLimit", "addressesUsed", "addressesRemaining", "upgrade"] }, "TrialUsage": { "type": "object", "description": "Alleen bij aanroepen met een proefsleutel: het verbruik van unieke adressen.", "properties": { "addressesUsed": { "type": "integer", "examples": [3] }, "addressLimit": { "type": "integer", "examples": [20] }, "addressesRemaining": { "type": "integer", "description": "Noem dit aan de gebruiker als het laag wordt.", "examples": [17] }, "upgrade": { "type": "string", "format": "uri", "description": "Registratie-URL voor een betaalde API-key." } }, "required": ["addressesUsed", "addressLimit", "addressesRemaining", "upgrade"] } } } }