{ "openapi": "3.0.1", "info": { "title": "WozApi", "description": "WOZ-waarden, BAG-adresgegevens, WOZ-object en kadastrale percelen uit 1 endpoint.\n\n**Base URL:** `https://woz-api.nl`\n\n**Authenticatie:** stuur je key mee als header `X-Api-Key: {key}` of als `Authorization: ApiKey {key}`. Een key maak je aan onder [API sleutels](/ApiKeys). Een sleutel hoort in een header, nooit in een URL.\n\n**Voor softwareleveranciers (OAuth-koppeling):** laat je klant zijn eigen WozApi-account koppelen via OAuth 2.0 (authorization code met PKCE) en stuur diens access token mee als `Authorization: Bearer {token}`. De credits gaan dan van het account van je klant af. Scopes: `woz.lookup` en `account.saldo`. Discovery: `/.well-known/openid-configuration`. Uitleg en aanvraag: [woz-api.nl/woz-api-koppeling](https://woz-api.nl/woz-api-koppeling).\n\n**Credits:** 1 credit is 1 uniek adres. Hetzelfde adres binnen 7 dagen opnieuw opvragen kost geen extra credit; dat is een kortingsregel en geen cache, de request wordt wel echt uitgevoerd. Een opvraging die op een fout eindigt (4xx of 5xx) kost niets, en een antwoord zonder WOZ-waarden (een lege `woz`) ook niet. Een nieuw account krijgt 10 gratis credits. Het resterende saldo staat in de response-header `X-Credits-Remaining` en is ook op te vragen via `GET /Api/Credits`. Is het saldo op, dan volgt 402 met code `InsufficientCredits`.\n\n**Zonder account:** vraag een gratis proefsleutel aan met `POST /Api/Proef` (5 unieke adressen, 10 met het e-mailadres van de gebruiker) en stuur hem mee als `X-Api-Key`. Zonder sleutel geeft de API 401 met code `SleutelOntbreekt`; een verbruikte proef geeft 402 met code `ProefVerbruikt`.\n\n**Een hele lijst:** `POST /Api/Lijst` met de adressen geeft een gratis proef van 5 adressen, de prijs voor de hele lijst en een betaalpagina voor de gebruiker; na betaling de rijen en het bestand.\n\n**AI-assistenten:** een MCP-server op `https://woz-api.nl/Api/Mcp`, en uitleg voor agents op [woz-api.nl/voor-ai-agents](https://woz-api.nl/voor-ai-agents).\n\n**Foutvorm:** elke fout geeft `{ fout, code, status, detail, traceId }` terug, zie het schema ApiFoutResponse. Dat geldt ook voor een 400 door modelvalidatie; `detail` bevat dan per veld de meldingen. Match in code op `code`, niet op de tekst in `fout`. Veelvoorkomende codes: `InvalidInput` (400), `Unauthorized` (401), `InsufficientCredits` (402), `AddressNotFound` en `NonResidential` (404), `PdokLookupFailed` (502) en `UpstreamUnavailable` (503). Een 502 of 503 kost niets; probeer het na een halve minuut opnieuw.\n\n**Voorbeeld:**\n\n```\ncurl \"https://woz-api.nl/Api/Adres?adres=Spuistraat%2036C,%201012TT%20Amsterdam\" \\\n -H \"X-Api-Key: JOUW_API_KEY\"\n```", "termsOfService": "https://woz-api.nl/terms", "contact": { "name": "WozApi", "url": "https://woz-api.nl/", "email": "info@woz-api.nl" }, "version": "v1" }, "servers": [ { "url": "https://woz-api.nl", "description": "Productie" } ], "paths": { "/Api/Credits": { "get": { "tags": [ "Account" ], "summary": "Huidig creditsaldo bij de meegestuurde API-key.", "description": "Kost zelf geen credit. Handig om vooraf te bewaken dat je niet tegen een 402 aanloopt,\r\nbijvoorbeeld voor een batch. Tijdens een reeks lookups kun je in plaats hiervan de\r\nresponse-header X-Credits-Remaining uitlezen, die na elke geslaagde call meekomt.\r\n \r\nDit endpoint vereist een key: anoniem toegang heeft geen saldo.", "responses": { "200": { "description": "Het saldo dat bij deze key hoort.", "headers": { "X-Credits-Remaining": { "description": "Aantal resterende credits na deze request. Alleen aanwezig bij requests met een geldige accountsessie of API-key.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/CreditsResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CreditsResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreditsResponse" } } } }, "401": { "description": "API-key ontbreekt of is ongeldig.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } } } } }, "/Api/Adres": { "get": { "tags": [ "Adressen" ], "summary": "WOZ-gegevens op basis van een volledig adres, bv. \"Kalverstraat 1, 1012NX Amsterdam\".", "description": "Kost 1 credit per uniek adres. Hetzelfde adres binnen 7 dagen opnieuw opvragen kost geen\r\nextra credit; dat is een kortingsregel en geen cache, de request wordt wel echt uitgevoerd.\r\nEen opvraging die op een fout eindigt (4xx of 5xx) kost geen credit, en een antwoord zonder\r\nWOZ-waarden (een lege woz, bijvoorbeeld een pand zonder openbare WOZ-waarde) ook niet.\r\n \r\nZonder account vraag je een gratis proefsleutel aan met POST /Api/Proef (5 unieke adressen,\r\n10 met het e-mailadres van de gebruiker). Met een key van een account gelden je credits en\r\nvolgt 402 als je saldo leeg is, met een betaallink in detail.betaalUrl. Het resterende saldo\r\nof proeftegoed staat in de response-header X-Credits-Remaining.", "parameters": [ { "name": "adres", "in": "query", "description": "Volledig adres met postcode of woonplaats.", "required": true, "schema": { "type": "string" } }, { "name": "geometrie", "in": "query", "description": "Zet op true om de perceelgrenzen als GeoJSON mee te sturen. Maakt de respons flink groter.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Gevonden. Bevat WOZ-waarden per peildatum, BAG-gegevens, WOZ-object en percelen.", "headers": { "X-Credits-Remaining": { "description": "Aantal resterende credits na deze request. Alleen aanwezig bij requests met een geldige accountsessie of API-key.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/WozApiResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/WozApiResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/WozApiResponse" } } } }, "400": { "description": "Parameter 'adres' ontbreekt of is onbruikbaar.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } }, "401": { "description": "Geen sleutel (SleutelOntbreekt, vraag een proefsleutel aan met POST /Api/Proef), of een ongeldige of verlopen sleutel.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } }, "402": { "description": "Creditsaldo is leeg (InsufficientCredits, met detail.betaalUrl), of de gratis proef is op (ProefVerbruikt).", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } }, "403": { "description": "Een OAuth-token zonder de scope woz.lookup (ScopeOntbreekt).", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } }, "404": { "description": "Geen WOZ-object gevonden voor dit adres.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } }, "502": { "description": "Bad Gateway", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } } } } }, "/Api/Nummeraanduiding/{id}": { "get": { "tags": [ "Adressen" ], "summary": "WOZ-gegevens op basis van BAG nummeraanduiding-id.", "description": "Gebruik dit endpoint als je de BAG-id's al hebt, bijvoorbeeld uit een eerdere adres-lookup\r\nof uit een eigen BAG-import. Het slaat het opzoeken van het adres over, dus je bent niet\r\nafhankelijk van de schrijfwijze van een adres. Een nummeraanduiding is de brievenbus, een\r\nadresseerbaar object het verblijfsobject erachter; kies /Api/AdresseerbaarObject als je een\r\nverblijfsobject-id hebt.\r\n \r\nDezelfde creditregels als /Api/Adres: 1 credit per uniek adres, 7 dagen herhalen zonder\r\nextra credit, en een fout of een antwoord zonder WOZ-waarden kost niets.", "parameters": [ { "name": "id", "in": "path", "description": "BAG nummeraanduiding-id (16 cijfers).", "required": true, "schema": { "type": "string" } }, { "name": "geometrie", "in": "query", "description": "Zet op true om de perceelgrenzen als GeoJSON mee te sturen. Maakt de respons flink groter.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Gevonden.", "headers": { "X-Credits-Remaining": { "description": "Aantal resterende credits na deze request. Alleen aanwezig bij requests met een geldige accountsessie of API-key.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/WozApiResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/WozApiResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/WozApiResponse" } } } }, "400": { "description": "Het id ontbreekt of heeft niet de vorm van een BAG-id.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } }, "401": { "description": "Geen sleutel (SleutelOntbreekt), of een ongeldige of verlopen sleutel.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } }, "402": { "description": "Creditsaldo is leeg (InsufficientCredits), of de gratis proef is op (ProefVerbruikt).", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } }, "403": { "description": "Een OAuth-token zonder de scope woz.lookup (ScopeOntbreekt).", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } }, "404": { "description": "Geen WOZ-object gevonden voor dit id.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } } } } }, "/Api/AdresseerbaarObject/{id}": { "get": { "tags": [ "Adressen" ], "summary": "WOZ-gegevens op basis van BAG adresseerbaar object-id.", "description": "Voor wie een verblijfsobject-id heeft in plaats van een adres of nummeraanduiding. Zelfde\r\ncreditregels als /Api/Adres: 1 credit per uniek adres, 7 dagen herhalen zonder extra\r\ncredit, en een fout of een antwoord zonder WOZ-waarden kost niets.", "parameters": [ { "name": "id", "in": "path", "description": "BAG adresseerbaar object-id (16 cijfers).", "required": true, "schema": { "type": "string" } }, { "name": "geometrie", "in": "query", "description": "Zet op true om de perceelgrenzen als GeoJSON mee te sturen. Maakt de respons flink groter.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Gevonden.", "headers": { "X-Credits-Remaining": { "description": "Aantal resterende credits na deze request. Alleen aanwezig bij requests met een geldige accountsessie of API-key.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/WozApiResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/WozApiResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/WozApiResponse" } } } }, "400": { "description": "Het id ontbreekt of heeft niet de vorm van een BAG-id.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } }, "401": { "description": "Geen sleutel (SleutelOntbreekt), of een ongeldige of verlopen sleutel.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } }, "402": { "description": "Creditsaldo is leeg (InsufficientCredits), of de gratis proef is op (ProefVerbruikt).", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } }, "403": { "description": "Een OAuth-token zonder de scope woz.lookup (ScopeOntbreekt).", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } }, "404": { "description": "Geen WOZ-object gevonden voor dit id.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } } } } }, "/Api/Lijst": { "post": { "tags": [ "Lijst" ], "summary": "Een nieuwe lijst, uit adressen of een bestand.", "description": "Geef de adressen mee in `adressen`, elk als tekst (\"Spuistraat 36C, 1012 TT Amsterdam\") of als\r\nobject met straat, huisnummer, huisletter, toevoeging, postcode en plaats; `ref` en `jaar`\r\nper adres mogen erbij. Of stuur een Excel- of CSV-bestand in base64 in `bestand`, met\r\n`bestandsnaam`. Hebben de adressen geen postcode of plaats, geef dan `plaats` mee.\r\n \r\nDaarna loopt de gratis proef: we zoeken alle adressen op en vragen er vijf op. Vraag de stand op\r\nmet GET op links.status, met ?wacht=20 om te wachten tot hij klaar is. Dezelfde lijst binnen een\r\nuur opnieuw sturen geeft dezelfde lijst terug.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LijstAanvraag" } }, "text/json": { "schema": { "$ref": "#/components/schemas/LijstAanvraag" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/LijstAanvraag" } } } }, "responses": { "200": { "description": "De lijst en zijn stand.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LijstAntwoord" } } } }, "400": { "description": "Onbruikbare invoer (InvalidInput, TeVeelAdressen, EmailOngeldig).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } }, "401": { "description": "Geen sleutel in de header (SleutelOntbreekt) of een verlopen proefsleutel (SleutelVerlopen).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } }, "403": { "description": "Een OAuth-token (ScopeOntbreekt).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } }, "429": { "description": "Vandaag al genoeg lijsten met deze sleutel, of de gratis proeven zijn vol (TeVeelLijsten).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } } } } }, "/Api/Lijst/Upload": { "post": { "tags": [ "Lijst" ], "summary": "Een nieuwe lijst uit een bestand, als multipart-upload.", "description": "Het veld `bestand` met een .xlsx, .xls of .csv; `plaats` en `email` mogen erbij.", "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "bestand": { "type": "string", "format": "binary" }, "plaats": { "type": "string" }, "email": { "type": "string" } } }, "encoding": { "bestand": { "style": "form" }, "plaats": { "style": "form" }, "email": { "style": "form" } } } } }, "responses": { "200": { "description": "De lijst en zijn stand.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LijstAntwoord" } } } }, "400": { "description": "Geen of een onleesbaar bestand.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } }, "401": { "description": "Geen sleutel in de header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } } } } }, "/Api/Lijst/{token}": { "get": { "tags": [ "Lijst" ], "summary": "De stand van een lijst.", "description": "Met `wacht` (hoogstens 25 seconden) wacht de aanroep tot de proef of de verwerking verder is,\r\nzodat je niet hoeft te blijven vragen. Wie het token heeft, kan de lijst lezen: geef het alleen\r\naan de gebruiker.", "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "wacht", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 0 } } ], "responses": { "200": { "description": "De stand.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LijstAntwoord" } } } }, "404": { "description": "Deze lijst bestaat niet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } }, "410": { "description": "De API-toegang tot deze lijst is verlopen (LijstVerlopen).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } } } } }, "/Api/Lijst/{token}/Kolommen": { "post": { "tags": [ "Lijst" ], "summary": "De kolommen van een bestand kiezen.", "description": "Alleen nodig bij status kolommen_kiezen. Kolommen tellen vanaf 0 (kolommen.lijst). Kies je alleen\r\n`adres`, dan zoeken wij de postcode- en plaatskolom erbij. Zonder postcode en plaats in het\r\nbestand: geef `vastePlaats` mee.", "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LijstKolomKeuze" } }, "text/json": { "schema": { "$ref": "#/components/schemas/LijstKolomKeuze" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/LijstKolomKeuze" } } } }, "responses": { "200": { "description": "De nieuwe stand; de proef begint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LijstAntwoord" } } } }, "400": { "description": "Een kolom die niet bestaat, of een kolom zonder adressen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } }, "409": { "description": "De kolommen liggen al vast (LijstNietKlaar, LijstAlBetaald).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } } } } }, "/Api/Lijst/{token}/Betaallink": { "post": { "tags": [ "Lijst" ], "summary": "De betaallink van een lijst.", "description": "Bij status wacht_op_betaling. Geeft de pagina waar de gebruiker de proef en de prijs ziet en zelf\r\nmet iDEAL betaalt; openen start nog geen betaling. Met `email` staat het eigen e-mailadres van\r\nde gebruiker daar al ingevuld: daar komen het bestand en de factuur. Verzin nooit een e-mailadres.", "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LijstBetaallinkAanvraag" } }, "text/json": { "schema": { "$ref": "#/components/schemas/LijstBetaallinkAanvraag" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/LijstBetaallinkAanvraag" } } } }, "responses": { "200": { "description": "De stand met betaling.betaalUrl.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LijstAntwoord" } } } }, "400": { "description": "Een onbruikbaar e-mailadres (EmailOngeldig).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } }, "409": { "description": "Er valt (nog) niets te betalen (LijstNietBetaalbaar), of er is al betaald (LijstAlBetaald).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } } } } }, "/Api/Lijst/{token}/Resultaten": { "get": { "tags": [ "Lijst" ], "summary": "De rijen van een geleverde lijst.", "description": "In de volgorde van de invoer, hoogstens 500 per pagina; `volgende` wijst naar de volgende pagina.", "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "vanaf", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "name": "aantal", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100 } } ], "responses": { "200": { "description": "Een pagina rijen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LijstResultaten" } } } }, "409": { "description": "Nog niet betaald en verwerkt (LijstNietKlaar).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } }, "410": { "description": "De API-toegang is verlopen (LijstVerlopen).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } } } } }, "/Api/Lijst/{token}/Download": { "get": { "tags": [ "Lijst" ], "summary": "Het bestand van een geleverde lijst, met de WOZ-kolommen erbij.", "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Het bestand." }, "409": { "description": "Nog niet betaald en verwerkt (LijstNietKlaar).", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "text/csv": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } }, "410": { "description": "Niet meer beschikbaar (LijstVerlopen).", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "text/csv": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } } } } }, "/Api/Proef": { "post": { "tags": [ "Proef" ], "summary": "Een gratis proefsleutel, zonder account.", "description": "Geeft een sleutel voor 5 unieke adressen. Met het e-mailadres van de gebruiker worden het er\r\n10 in totaal en ontstaat er een WozApi-account zonder wachtwoord; de gebruiker krijgt daar een\r\nmail over. De proef telt unieke adressen: hetzelfde adres opnieuw is gratis, en een fout of een\r\nadres zonder WOZ-waarde kost niets.\r\n \r\nVraag per gesprek hoogstens een proefsleutel aan, en geen nieuwe als de proef op is.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProefAanvraag" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProefAanvraag" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/ProefAanvraag" } } } }, "responses": { "200": { "description": "De sleutel en het tegoed. De sleutel is alleen in dit antwoord te zien.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProefSleutelAntwoord" } } } }, "400": { "description": "Het e-mailadres is onbruikbaar (EmailOngeldig).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } }, "429": { "description": "Te veel sleutels vanaf dit netwerk (TeVeelProefsleutels) of te snel achter elkaar (TeVeelVerzoeken).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } } } } }, "/Api/Proef/Email": { "post": { "tags": [ "Proef" ], "summary": "Het e-mailadres van de gebruiker bij een proefsleutel.", "description": "Met het eigen e-mailadres van de gebruiker worden het 10 adressen in totaal. Er ontstaat een\r\naccount zonder wachtwoord, en de gebruiker krijgt een mail met uitleg; daarna koopt hij credits\r\nvia een betaallink. Heeft dit adres al een account, dan koppelen we de sleutel daar niet aan:\r\ndat gebeurt pas als de gebruiker zelf inlogt. Het antwoord is in beide gevallen hetzelfde.\r\nVerzin nooit een e-mailadres.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProefEmailAanvraag" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProefEmailAanvraag" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/ProefEmailAanvraag" } } } }, "responses": { "200": { "description": "Het nieuwe tegoed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProefEmailAntwoord" } } } }, "400": { "description": "Het e-mailadres is onbruikbaar (EmailOngeldig).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } }, "401": { "description": "Geen sleutel, of een verlopen sleutel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } }, "409": { "description": "Aan deze sleutel hangt al een ander e-mailadres (SleutelHeeftAlEmail).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } } } } }, "/Api/Opwaarderen": { "post": { "tags": [ "Proef" ], "summary": "Een betaallink voor credits.", "description": "Geeft een link die je aan de gebruiker geeft. Hij ziet daar eerst wat hij koopt en betaalt\r\ndaarna zelf met iDEAL; openen start nog geen betaling. De credits staan direct na betaling\r\nop het account en de factuur komt per mail. Een proefsleutel zonder e-mailadres heeft nog\r\ngeen account: stuur eerst het e-mailadres met POST /Api/Proef/Email.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpwaardeerAanvraag" } }, "text/json": { "schema": { "$ref": "#/components/schemas/OpwaardeerAanvraag" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/OpwaardeerAanvraag" } } } }, "responses": { "200": { "description": "De betaallink met het bedrag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BetaalLinkAntwoord" } } } }, "400": { "description": "Geen geldig aantal credits; detail.geldigeAantallen noemt ze.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } }, "401": { "description": "Geen sleutel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } }, "403": { "description": "Betalen staat tijdelijk uit (PaymentsDisabled).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } }, "409": { "description": "Eerst het e-mailadres van de gebruiker (EmailNodig).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiFoutResponse" } } } } } } } }, "components": { "schemas": { "ApiFoutResponse": { "type": "object", "properties": { "fout": { "type": "string", "description": "Foutmelding in het Nederlands, bedoeld om te tonen aan een eindgebruiker.", "nullable": true, "example": "Ongeldige API-key." }, "code": { "type": "string", "description": "Stabiele foutcode om in code op te matchen. Niet elke fout heeft er een; bij een\r\nonverwachte fout is dit veld null.", "nullable": true, "example": "Unauthorized" }, "status": { "type": "integer", "description": "De HTTP-statuscode, ook in de body zodat loggen zonder response-object werkt.", "format": "int32", "example": 401 }, "detail": { "description": "Extra toelichting waar die bestaat, anders null. Dit is soms een tekst en soms een\r\nobject (bijvoorbeeld met de gezochte term en een hint), dus lees het als vrije JSON.", "nullable": true }, "traceId": { "type": "string", "description": "Correlatie-id van de request. Vermeld dit bij een supportvraag.", "nullable": true, "example": "0HN7GK2P3QJ1M:00000003" } }, "additionalProperties": false, "description": "De foutrespons die de API werkelijk teruggeeft. Bestaat omdat de OpenAPI-spec bij 400, 401,\r\n402 en 404 naar ProblemDetails verwees, terwijl\r\nWozApi.Middleware.ErrorHandlingMiddleware een heel andere vorm stuurt. Wie op de\r\ndocumentatie bouwde, parseerde dus elke fout verkeerd." }, "BagInfo": { "type": "object", "properties": { "adresseerbaarobjectId": { "type": "string", "nullable": true }, "nummeraanduidingId": { "type": "string", "nullable": true }, "straatnaam": { "type": "string", "nullable": true }, "huisnummer": { "type": "integer", "format": "int32" }, "postcode": { "type": "string", "nullable": true }, "woonplaatsnaam": { "type": "string", "nullable": true } }, "additionalProperties": false }, "BetaalBedragInfo": { "type": "object", "properties": { "prijsPerCreditExclBtw": { "type": "number", "format": "double" }, "exclBtw": { "type": "number", "format": "double" }, "btw": { "type": "number", "format": "double" }, "inclBtw": { "type": "number", "format": "double" }, "valuta": { "type": "string", "nullable": true } }, "additionalProperties": false, "description": "Een bedrag in euro's, met en zonder 21% btw." }, "BetaalLinkAntwoord": { "type": "object", "properties": { "betaalUrl": { "type": "string", "description": "De link voor de gebruiker. Openen start nog geen betaling.", "nullable": true }, "credits": { "type": "integer", "format": "int32" }, "bedrag": { "$ref": "#/components/schemas/BetaalBedragInfo" }, "geldigTot": { "type": "string", "description": "Tot wanneer de link werkt.", "format": "date-time" }, "geldigeAantallen": { "type": "array", "items": { "type": "integer", "format": "int32" }, "description": "De aantallen credits die je kunt kopen.", "nullable": true }, "uitleg": { "type": "string", "description": "Wat de gebruiker ziet en wat er daarna gebeurt.", "nullable": true } }, "additionalProperties": false, "description": "Een betaallink voor credits. De gebruiker betaalt zelf, in zijn browser." }, "CreditsResponse": { "type": "object", "properties": { "credits": { "type": "integer", "format": "int32" }, "tegoed": { "$ref": "#/components/schemas/TegoedInfo" } }, "additionalProperties": false }, "KadastraalObjectInfo": { "type": "object", "properties": { "kadastraleGemeenteCode": { "type": "string", "description": "Code van de kadastrale gemeente, bijvoorbeeld \"ASD00\".", "nullable": true }, "kadastraleSectie": { "type": "string", "description": "Sectieletter binnen de kadastrale gemeente, bijvoorbeeld \"K\".", "nullable": true }, "kadastraalPerceelNummer": { "type": "string", "description": "Perceelnummer binnen de sectie.", "nullable": true }, "aanduiding": { "type": "string", "description": "De drie delen samengevoegd, bijvoorbeeld \"ASD00 K 1234\".", "nullable": true } }, "additionalProperties": false, "description": "Kadastrale aanduiding van het perceel waarop het WOZ-object ligt." }, "LijstAantallen": { "type": "object", "properties": { "rijen": { "type": "integer", "description": "Regels in de lijst, lege meegeteld.", "format": "int32" }, "uniek": { "type": "integer", "description": "Verschillende adressen; een dubbel adres telt en kost een keer.", "format": "int32" }, "herkend": { "type": "integer", "format": "int32", "nullable": true }, "nietGevonden": { "type": "integer", "format": "int32", "nullable": true }, "geenWoz": { "type": "integer", "format": "int32", "nullable": true }, "mislukt": { "type": "integer", "format": "int32", "nullable": true }, "gevonden": { "type": "integer", "description": "Met een WOZ-waarde in het resultaat; pas na de verwerking.", "format": "int32", "nullable": true } }, "additionalProperties": false }, "LijstAanvraag": { "type": "object", "properties": { "adressen": { "type": "array", "items": { "$ref": "#/components/schemas/LijstAdres" }, "description": "De adressen, elk als tekst (\"Spuistraat 36C, 1012 TT Amsterdam\") of als object met straat,\r\nhuisnummer, huisletter, toevoeging, postcode, plaats, en eventueel ref en jaar.", "nullable": true }, "bestand": { "type": "string", "description": "Een Excel- of CSV-bestand in base64, in plaats van adressen.", "nullable": true }, "bestandsnaam": { "type": "string", "description": "Naam van dat bestand, met extensie (.xlsx, .xls of .csv).", "nullable": true }, "plaats": { "type": "string", "description": "De plaats voor alle adressen zonder postcode of plaats. \"Kerkstraat 12\" bestaat in veel plaatsen.", "nullable": true }, "email": { "type": "string", "description": "Het eigen e-mailadres van de gebruiker voor de levering; alvast ingevuld op de betaalpagina.", "nullable": true } }, "additionalProperties": false, "description": "Een nieuwe lijst: adressen, of een bestand in base64." }, "LijstAdres": { "type": "object", "properties": { "tekst": { "type": "string", "description": "Het hele adres als tekst. Wint van de losse velden als beide er zijn.", "nullable": true }, "straat": { "type": "string", "nullable": true }, "huisnummer": { "type": "string", "nullable": true }, "huisletter": { "type": "string", "nullable": true }, "toevoeging": { "type": "string", "nullable": true }, "postcode": { "type": "string", "nullable": true }, "plaats": { "type": "string", "nullable": true }, "ref": { "type": "string", "description": "Een eigen kenmerk van de gebruiker (objectnummer, regelnummer); komt terug in het bestand.", "nullable": true }, "jaar": { "type": "string", "description": "Een jaartal per adres, voor de keuze \"per rij uit een kolom\" op de betaalpagina.", "nullable": true } }, "additionalProperties": false, "description": "Een adres in een lijst van de API: een tekst (\"Spuistraat 36C, 1012 TT Amsterdam\") of losse\r\nvelden. Een AI-assistent heeft meestal het een of het ander, en we willen hem niet laten kiezen." }, "LijstAntwoord": { "type": "object", "properties": { "token": { "type": "string", "description": "Het token van de lijst: wie het heeft, kan de lijst lezen en betalen. Niet in een URL voor derden zetten.", "nullable": true }, "status": { "type": "string", "description": "kolommen_kiezen, proef_bezig, niets_herkend, wacht_op_betaling, bezig, klaar of mislukt.", "nullable": true }, "volgendeStap": { "$ref": "#/components/schemas/LijstVolgendeStap" }, "avg": { "type": "string", "description": "Hoe de gebruiker met de uitkomst omgaat.", "nullable": true }, "aantallen": { "$ref": "#/components/schemas/LijstAantallen" }, "proef": { "type": "array", "items": { "$ref": "#/components/schemas/LijstProefRij" }, "nullable": true }, "prijs": { "$ref": "#/components/schemas/LijstPrijs" }, "betaling": { "$ref": "#/components/schemas/LijstBetaling" }, "voortgang": { "$ref": "#/components/schemas/LijstVoortgang" }, "kolommen": { "$ref": "#/components/schemas/LijstKolommen" }, "links": { "$ref": "#/components/schemas/LijstLinks" }, "volgendeControleNaSeconden": { "type": "integer", "description": "Na zoveel seconden is er waarschijnlijk iets veranderd; leeg als er niets te wachten valt.", "format": "int32", "nullable": true }, "aangemaaktOp": { "type": "string", "format": "date-time" }, "geleverdOp": { "type": "string", "format": "date-time", "nullable": true }, "apiToegangTot": { "type": "string", "description": "Tot wanneer de API deze lijst nog toont; de link uit de bezorgmail blijft daarna werken.", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "De stand van een lijst. Elk veld dat in deze stand niets zegt, ontbreekt." }, "LijstBetaallinkAanvraag": { "type": "object", "properties": { "email": { "type": "string", "nullable": true } }, "additionalProperties": false, "description": "Het e-mailadres voor de levering bij het opvragen van de betaallink." }, "LijstBetaling": { "type": "object", "properties": { "betaalUrl": { "type": "string", "description": "De pagina waar de gebruiker de proef ziet en zelf met iDEAL betaalt. Openen start nog geen betaling.", "nullable": true }, "emailBekend": { "type": "boolean", "description": "Of er al een e-mailadres voor de levering is; zo niet, dan vraagt de betaalpagina erom." }, "uitleg": { "type": "string", "nullable": true } }, "additionalProperties": false }, "LijstHistorieWaarde": { "type": "object", "properties": { "peildatum": { "type": "string", "nullable": true }, "wozJaar": { "type": "integer", "format": "int32", "nullable": true }, "wozWaarde": { "type": "integer", "format": "int64" } }, "additionalProperties": false }, "LijstKolom": { "type": "object", "properties": { "index": { "type": "integer", "format": "int32" }, "naam": { "type": "string", "nullable": true } }, "additionalProperties": false }, "LijstKolomKeuze": { "type": "object", "properties": { "adres": { "type": "integer", "description": "De kolom met het hele adres. Dan zoeken wij de postcode- en plaatskolom erbij.", "format": "int32", "nullable": true }, "straat": { "type": "integer", "format": "int32", "nullable": true }, "huisnummer": { "type": "integer", "format": "int32", "nullable": true }, "huisletter": { "type": "integer", "format": "int32", "nullable": true }, "toevoeging": { "type": "integer", "format": "int32", "nullable": true }, "postcode": { "type": "integer", "format": "int32", "nullable": true }, "plaats": { "type": "integer", "format": "int32", "nullable": true }, "kopregel": { "type": "integer", "description": "De rij met kolomnamen (vanaf 0), of -1 als het bestand er geen heeft. Leeg: zoals we hem vonden.", "format": "int32", "nullable": true }, "vastePlaats": { "type": "string", "description": "De plaats voor alle adressen, als het bestand geen postcode en geen plaats heeft.", "nullable": true } }, "additionalProperties": false, "description": "De kolomkeuze bij een bestand waarvan we de adreskolom niet zeker wisten. Kolommen tellen vanaf 0." }, "LijstKolommen": { "type": "object", "properties": { "lijst": { "type": "array", "items": { "$ref": "#/components/schemas/LijstKolom" }, "nullable": true }, "voorbeeld": { "type": "array", "items": { "type": "array", "items": { "type": "string" } }, "description": "De eerste regels onder de kop, om de kolom te kunnen kiezen.", "nullable": true }, "voorstel": { "$ref": "#/components/schemas/LijstKolomKeuze" }, "plaatsNodig": { "type": "boolean", "description": "Of het bestand geen postcode en geen plaats heeft; geef dan vastePlaats mee." } }, "additionalProperties": false, "description": "Bij een bestand waarvan we de adreskolom niet zeker wisten: de kolommen en een paar regels." }, "LijstLinks": { "type": "object", "properties": { "status": { "type": "string", "description": "Deze stand opnieuw opvragen.", "nullable": true }, "pagina": { "type": "string", "description": "De pagina voor de gebruiker zelf, met proef, betalen en download.", "nullable": true }, "kolommen": { "type": "string", "nullable": true }, "betaallink": { "type": "string", "nullable": true }, "resultaten": { "type": "string", "nullable": true }, "download": { "type": "string", "nullable": true } }, "additionalProperties": false }, "LijstPrijs": { "type": "object", "properties": { "adressen": { "type": "integer", "description": "Het aantal adressen dat de gebruiker betaalt: alle herkende, de proefadressen inbegrepen.", "format": "int32" }, "prijsPerAdresExclBtw": { "type": "number", "format": "double", "nullable": true }, "exclBtw": { "type": "number", "format": "double" }, "btw": { "type": "number", "format": "double" }, "inclBtw": { "type": "number", "format": "double" }, "valuta": { "type": "string", "nullable": true }, "uitleg": { "type": "string", "nullable": true } }, "additionalProperties": false }, "LijstProefRij": { "type": "object", "properties": { "rij": { "type": "integer", "description": "Positie in de lijst, vanaf 1; leeg bij een proef van voor 27 september 2026.", "format": "int32", "nullable": true }, "invoer": { "type": "string", "nullable": true }, "adres": { "type": "string", "description": "Het adres zoals wij het vonden.", "nullable": true }, "status": { "type": "string", "description": "gevonden, geen_woz, niet_gevonden of mislukt.", "nullable": true }, "wozWaarde": { "type": "integer", "format": "int64", "nullable": true }, "wozJaar": { "type": "integer", "description": "Het belastingjaar van die waarde: peildatum 1 januari 2025 is WOZ-jaar 2026.", "format": "int32", "nullable": true }, "peildatum": { "type": "string", "nullable": true } }, "additionalProperties": false, "description": "Een rij uit de gratis proef." }, "LijstResultaatRij": { "type": "object", "properties": { "rij": { "type": "integer", "description": "Positie in de lijst, vanaf 1. Een lege regel uit de invoer staat er niet in.", "format": "int32" }, "invoer": { "type": "string", "nullable": true }, "adres": { "type": "string", "nullable": true }, "status": { "type": "string", "description": "gevonden, geen_woz, niet_gevonden of mislukt.", "nullable": true }, "wozWaarde": { "type": "integer", "format": "int64", "nullable": true }, "wozJaar": { "type": "integer", "format": "int32", "nullable": true }, "peildatum": { "type": "string", "nullable": true }, "oppervlakte": { "type": "integer", "format": "int32", "nullable": true }, "historie": { "type": "array", "items": { "$ref": "#/components/schemas/LijstHistorieWaarde" }, "description": "Eerdere WOZ-waarden van dit adres, nieuwste eerst.", "nullable": true } }, "additionalProperties": false }, "LijstResultaten": { "type": "object", "properties": { "token": { "type": "string", "nullable": true }, "vanaf": { "type": "integer", "format": "int32" }, "totaal": { "type": "integer", "format": "int32" }, "rijen": { "type": "array", "items": { "$ref": "#/components/schemas/LijstResultaatRij" }, "nullable": true }, "volgende": { "type": "string", "description": "De volgende pagina, of leeg als dit de laatste was.", "nullable": true }, "avg": { "type": "string", "nullable": true } }, "additionalProperties": false, "description": "Een pagina rijen van een geleverde lijst." }, "LijstVolgendeStap": { "type": "object", "properties": { "code": { "type": "string", "description": "Vaste code om op te beslissen: kolom_kiezen, wachten, niets_herkend, betaallink_geven, verwerken, klaar, mislukt.", "nullable": true }, "tekst": { "type": "string", "nullable": true } }, "additionalProperties": false }, "LijstVoortgang": { "type": "object", "properties": { "verwerkt": { "type": "integer", "format": "int32" }, "totaal": { "type": "integer", "format": "int32" }, "geschatKlaarOp": { "type": "string", "description": "Een schatting; lijsten worden een voor een verwerkt.", "format": "date-time", "nullable": true } }, "additionalProperties": false }, "OpwaardeerAanvraag": { "type": "object", "properties": { "credits": { "type": "integer", "description": "Aantal credits; leeg is het kleinste pakket. Zie geldigeAantallen.", "format": "int32", "nullable": true, "example": 100 } }, "additionalProperties": false, "description": "Verzoek om een betaallink voor credits." }, "PerceelInfo": { "type": "object", "properties": { "aanduiding": { "type": "string", "description": "Kadastrale aanduiding, bijvoorbeeld \"ASD04 F 1145\".", "nullable": true }, "kadastraleGemeenteCode": { "type": "string", "description": "AKR-code van de kadastrale gemeente, bijvoorbeeld \"ASD04\".", "nullable": true }, "kadastraleGemeente": { "type": "string", "description": "Naam van de kadastrale gemeente, bijvoorbeeld \"Amsterdam\".", "nullable": true }, "kadastraleSectie": { "type": "string", "nullable": true }, "perceelnummer": { "type": "integer", "format": "int32" }, "oppervlakteM2": { "type": "integer", "description": "Kadastrale grootte van het perceel in m2.", "format": "int32", "nullable": true }, "soortGrootte": { "type": "string", "description": "\"Vastgesteld\" of \"Voorlopig\", zoals het Kadaster de grootte kwalificeert.", "nullable": true }, "perceelId": { "type": "string", "description": "Lokale identificatie van het kadastrale object binnen NL.IMKAD.KadastraalObject.", "nullable": true }, "geometrie": { "description": "Perceelgrens als GeoJSON-geometrie in WGS84 (EPSG:4326).\r\nAlleen gevuld bij `?geometrie=true`, omdat het de respons flink groter maakt.", "nullable": true } }, "additionalProperties": false, "description": "Perceel uit de open Kadastrale Kaart, gekoppeld aan dit adres via de BAG.\r\nDit is de actuele perceelsituatie en kan afwijken van WozApi.Models.ViewModels.WozApiResponse.KadastraleObjecten,\r\ndat de aanduiding geeft waar de WOZ-registratie aan hangt." }, "ProefAanvraag": { "type": "object", "properties": { "email": { "type": "string", "description": "Het eigen e-mailadres van de gebruiker, alleen als hij het zelf voor dit doel gaf. Met een\r\ne-mailadres worden het 10 adressen in totaal en ontstaat er een account zonder wachtwoord.\r\nVerzin er nooit een.", "nullable": true }, "kanaal": { "type": "string", "description": "Waar de aanvraag vandaan komt: \"api\" (standaard), \"demo\" of \"mcp\".", "nullable": true } }, "additionalProperties": false, "description": "Verzoek om een gratis proefsleutel. Beide velden zijn optioneel; een lege body mag." }, "ProefEmailAanvraag": { "type": "object", "properties": { "email": { "type": "string", "description": "Het eigen e-mailadres van de gebruiker. Verzin er nooit een.", "nullable": true } }, "additionalProperties": false, "description": "Het e-mailadres van de gebruiker bij een proefsleutel." }, "ProefEmailAntwoord": { "type": "object", "properties": { "tegoed": { "$ref": "#/components/schemas/TegoedInfo" }, "melding": { "type": "string", "description": "Wat er met het e-mailadres gebeurt.", "nullable": true } }, "additionalProperties": false, "description": "Antwoord op de e-mailstap: het nieuwe tegoed." }, "ProefSleutelAntwoord": { "type": "object", "properties": { "sleutel": { "type": "string", "description": "De sleutel. Stuur hem mee als header X-Api-Key, nooit in een URL.", "nullable": true, "example": "woz_Qm9BvX1kLp7Zt3YwR8sHn2JcF6gDaE4uVo5iKq0yTbM" }, "tegoed": { "$ref": "#/components/schemas/TegoedInfo" }, "email": { "type": "string", "description": "\"ontvangen\" als er een e-mailadres meekwam, anders leeg.", "nullable": true }, "gebruik": { "type": "string", "description": "Hoe je de sleutel gebruikt.", "nullable": true }, "regels": { "type": "array", "items": { "type": "string" }, "description": "Regels voor wie namens een gebruiker opvraagt.", "nullable": true } }, "additionalProperties": false, "description": "Een nieuwe proefsleutel. De sleutel is alleen in dit antwoord te zien." }, "TegoedInfo": { "type": "object", "properties": { "soort": { "type": "string", "description": "\"proef\" zolang de sleutel aan geen account hangt, \"credits\" als hij van een account is.", "nullable": true, "example": "proef" }, "limiet": { "type": "integer", "description": "Unieke adressen die deze proef in totaal mag; leeg bij credits.", "format": "int32", "nullable": true, "example": 5 }, "gebruikt": { "type": "integer", "description": "Unieke adressen die al gebruikt zijn; leeg bij credits.", "format": "int32", "nullable": true, "example": 1 }, "resterend": { "type": "integer", "description": "Wat er nog kan: adressen in de proef, of credits op het account.", "format": "int32", "example": 4 }, "verlooptOp": { "type": "string", "description": "Wanneer een proefsleutel zonder account vervalt.", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "Het tegoed van een proefsleutel of van een account dat een AI-assistent aanmaakte." }, "WozApiResponse": { "type": "object", "properties": { "adres": { "type": "string", "nullable": true }, "bag": { "$ref": "#/components/schemas/BagInfo" }, "wozObject": { "$ref": "#/components/schemas/WozObjectInfo" }, "kadastraleObjecten": { "type": "array", "items": { "$ref": "#/components/schemas/KadastraalObjectInfo" }, "description": "Een WOZ-object kan op meerdere percelen liggen, daarom een lijst.", "nullable": true }, "percelen": { "type": "array", "items": { "$ref": "#/components/schemas/PerceelInfo" }, "description": "Actuele percelen bij dit adres, met oppervlakte uit de Kadastrale Kaart.", "nullable": true }, "woz": { "type": "array", "items": { "$ref": "#/components/schemas/WozWaarden" }, "description": "Alle bekende peildata, oplopend gesorteerd: het eerste element is de oudste waarde en het\r\nlaatste de nieuwste. Wil je alleen de actuele waarde, gebruik dan HuidigeWaarde.", "nullable": true }, "huidigeWaarde": { "$ref": "#/components/schemas/WozWaarden" }, "tegoed": { "$ref": "#/components/schemas/TegoedInfo" } }, "additionalProperties": false }, "WozObjectInfo": { "type": "object", "properties": { "wozobjectnummer": { "type": "integer", "description": "Uniek nummer van het WOZ-object in de LV-WOZ.", "format": "int64", "nullable": true }, "grondoppervlakte": { "type": "integer", "description": "Oppervlakte van de grond in m2, indien bekend.", "format": "int32", "nullable": true } }, "additionalProperties": false, "description": "Het WOZ-object zelf, los van de vastgestelde waarden per peildatum." }, "WozWaarden": { "type": "object", "properties": { "peildatum": { "type": "string", "nullable": true }, "vastgesteldeWaarde": { "type": "integer", "format": "int32" } }, "additionalProperties": false } }, "securitySchemes": { "ApiKey": { "type": "apiKey", "description": "Gebruik je API key via header: X-Api-Key: {key} of Authorization: ApiKey {key}", "name": "X-Api-Key", "in": "header" }, "OAuth2": { "type": "oauth2", "description": "OAuth-koppeling voor softwareleveranciers: authorization code met PKCE. Je klant koppelt zijn eigen WozApi-account; credits gaan van diens saldo af.", "flows": { "authorizationCode": { "authorizationUrl": "https://woz-api.nl/connect/authorize", "tokenUrl": "https://woz-api.nl/connect/token", "scopes": { "woz.lookup": "WOZ-gegevens opvragen op de credits van de gekoppelde klant", "account.saldo": "Creditsaldo van de gekoppelde klant lezen" } } } } } }, "security": [ { "ApiKey": [ ] } ], "tags": [ { "name": "Adressen", "description": "Zelfde antwoord, drie manieren om het op te vragen: op adrestekst, of op een van de twee vaste BAG-sleutels." }, { "name": "Proef", "description": "Starten zonder account: een gratis proefsleutel, het e-mailadres van de gebruiker, en een betaallink voor credits. Voor AI-assistenten en scripts." }, { "name": "Lijst", "description": "Een hele lijst adressen of een Excel in een keer: een gratis proef van 5 adressen, de prijs en een betaallink, en na betaling de rijen en het bestand." }, { "name": "Account", "description": "Je creditsaldo uitlezen zonder een credit te verbruiken." } ] }