FunderMaps API v4

The FunderMaps webservice serves building-level foundation data to integrators: valuation chains, banks, insurers and municipalities. This document is the complete contract of the current version, v4. Anything not listed here is not part of the contract; if a response differs from what is documented, treat it as a defect and report it to us.

Production   https://ws.fundermaps.com/v4/...
Staging      https://ws-staging.fundermaps.com/v4/...

Staging serves the same production data with the same API key and is meant for trying an integration before pointing production traffic at it. Calls on either hostname are billed.

The previous version, /api/v3, was switched off on 2026-08-29 and now returns 404. If you are migrating an old v3 client, see Appendix: coming from v3.

1. Endpoints

Billing counts billable events: one event per (product, building) per 24 hours, regardless of how often you request it. Per-product usage limits may apply to your key; see rate limits.

Accepted {id} formats

Nummeraanduiding IDs are resolved to their pand before lookup. BAG address-to-building is many-to-one, so two nummeraanduidingen on the same pand return identical analysis and statistics — that's expected, the model is building-level.

Unrecognized or unresolvable IDs return a 404 with a structured error body — see Error responses.

/v4/product/risk and /v4/product/light

/v4/product/risk/{id} — a subset of analysis for valuation chains and dashboards. Returns: buildingId, foundationType, foundationTypeReliability, restorationCosts, inquiryType, drystandRisk, drystandReliability, bioInfectionRisk, bioInfectionReliability, dewateringDepthRisk, dewateringDepthReliability, unclassifiedRisk, recoveryType.

Field names and semantics are identical to the corresponding fields in analysis — note that the reliability fields are drystandReliability, bioInfectionReliability and dewateringDepthReliability (not …RiskReliability).

/v4/product/light/{id} — minimal response for fast integrations. Collapses the three component risks plus unclassifiedRisk (the construction-year-derived fallback classification) into a single derived overallRisk + overallRiskReliability. The fallback enters at indicative reliability, so it only determines overallRisk when no more reliable component risk is present — buildings covered only by the fallback report that class instead of null. If a recoveryType is set on the building (i.e. the foundation has been restored), overallRisk is forced to a with established reliability. Returns: overallRisk, overallRiskReliability — nothing else (restorationCosts and drystandRisk were removed from the response).

Research outcome endpoints

Where analysis returns the model-based risk assessment, these two endpoints return the summarized outcome of actually performed research on the building, where available. They complement analysis; they do not replace it.

/v4/product/facade_scan/{id} — the most recent facade scan (QuickScan) for the building, provided its report is less than 3 years old. Returns: buildingId, inquiryId, inquiryType (facade_scan), documentDate (YYYY-MM-DD), validUntil (documentDate + 3 years), facadeScanRisk (a–e), settlementSpeed, skewedParallelFacade, skewedPerpendicularFacade, facadeCrack, contractor, resource (optional, see below).

/v4/product/foundation-research/{id} — the most recent foundation research for the building, provided its report is less than 5 years old. Returns: buildingId, inquiryId, inquiryType (foundation_research), documentDate, validUntil (documentDate + 5 years), settlementSpeed, skewedParallelFacade, skewedPerpendicularFacade, facadeCrack, overallQuality, recoveryAdvised (boolean), enforcementTerm, contractor, resource (optional, see below).

Notes for both:

• All fields are nullable except buildingId. A null means the underlying report did not record that observation.

• resource — the source document. A link to the original report (normally a PDF) the outcome was taken from:

  "resource": {
    "url": "https://ams3.digitaloceanspaces.com/…/inquiry-report/8286ef68-….pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&…",
    "expiresAt": "2026-09-04T13:00:00.000Z",
    "mediaType": "application/pdf"
  }
  

  • url is a signed, short-lived link: it works for 1 hour from the moment of the response (expiresAt, ISO-8601 UTC), for anyone who holds it, with no further authentication. Fetch the document promptly; do not persist the URL — re-request the product to get a fresh one. Retrieving the document is not a separate billable call.
  • Freshness follows the data window. The link is included whenever the record itself is served: within 3 years for facade_scan, within 5 years for foundation-research. There is no separate age limit on the document.
  • Absent, never null. When the record has no source document on file, the resource key is omitted from the response entirely. Check for presence ("resource" in body), not for null.
  • mediaType is almost always application/pdf; a handful of legacy dossiers hold an image instead.

• Building-level: a nummeraanduiding resolves to its pand first, so two addresses on the same building return the same outcome — the research is attached to the building, not to one address.

• "Latest available" = the newest report by documentDate of that research type within the freshness window. A building whose only research is older than the window returns 404 no_data_available, same as a building never researched.

• The skew/settlement classifications use the same scale (nil → very_big) and derivation as the public facade-scan map layer; facadeCrack is the worst of the four facade crack observations.

Same authentication, ID formats, and error responses as analysis.

MCP endpoint for AI agents

POST /v4/mcp exposes the same products as an MCP server (Streamable HTTP, stateless, JSON responses), so an AI agent — Claude, ChatGPT, an in-house LLM tool — can call FunderMaps directly with your existing API key. Nothing else changes: the same Authorization: Bearer fmsk.… header, the same billing (a tool call is recorded as the corresponding product, with the same 24-hour deduplication), the same rate limits and the same error codes.

Tools:

Connecting (Claude Desktop / Claude Code / any Streamable-HTTP client):

{
  "mcpServers": {
    "fundermaps": {
      "type": "http",
      "url": "https://ws.fundermaps.com/v4/mcp",
      "headers": { "Authorization": "Bearer fmsk.your-key" }
    }
  }
}

Tool results carry the REST JSON body both as text and as structuredContent; a non-200 REST response becomes a tool error whose text starts with the REST code (no_data_available, rate_limit_exceeded, …) so the agent can pick the same follow-up a REST consumer would. The endpoint is POST-only: GET/DELETE return 405 because there are no sessions to resume or terminate.

2. Authentication

Every product call carries your API key as a standard Bearer token:

Authorization: Bearer fmsk.your_api_key

No other delivery method (query parameter, custom header) is accepted. Keys are issued by FunderMaps; contact us to add or rotate a key.

3. Analysis response reference

The complete field set of GET /v4/product/analysis/{id}. Nothing else is returned; any field not listed here is not part of the contract.

"Null share" is the proportion of the 11.2M buildings in the current model snapshot for which the field is null. It is guidance for sizing your handling of missing data, not a contract — shares move as the model is rebuilt.

Note the asymmetry in the reliability field names: constructionYearReliability and foundationTypeReliability are named after their value field, while drystandReliability, bioInfectionReliability and dewateringDepthReliability are not …RiskReliability. This matches v3 exactly; it is a quirk we preserved deliberately rather than a v4 change.

The *Reliability fields have never been null in any model snapshot to date, but treat them as nullable anyway — v3's non-nullable integer encoding could not express "unknown", and v4's can.

4. Statistics response

GET /v4/product/statistics/{id} returns aggregates for the neighborhood the building lies in (or for the CBS neighborhood given directly).

Enum values follow the enum reference.

5. Error responses

Every non-200 response has a consistent JSON body:

{ "code": "building_not_found", "message": "No data available for building 'NL.IMBAG.PAND.0599100000369041'." }

code is a stable, machine-readable identifier — switch on it in your integration. message is human-readable and may be reworded without notice; don't parse it.

The four 404 "no result" codes are designed so automated integrations (e.g. the NWWI valuation chain) can choose the correct follow-up action from code alone: a corrected resubmission (identifier_invalid, address_not_found), a QuickScan request (no_data_available), or no action (building_not_found, not_a_building).

New codes may be added over time; treat any unlisted code on an error status generically based on the HTTP status.

Rate limits

Usage limits are set per API key and product as a number of billable events per calendar day or month (UTC). When a limit applies, every response to that product carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the window resets); an exhausted limit returns 429 rate_limit_exceeded with Retry-After. Repeated requests for the same building within 24 hours do not consume additional events.

6. Every known building carries a risk indication

Since July 2026, the model guarantees that every building known to the model carries at least one risk indication. When none of the component risks (drystandRisk, bioInfectionRisk, dewateringDepthRisk) could be computed and no report-derived class exists — typically buildings outside groundwater-model coverage or with an undetermined foundation type — unclassifiedRisk contains a construction-year-based estimate:

Notes for interpreting responses:

• This fallback is indicative: it is a heuristic, not a computed or inspected result. It applies to roughly 0.4% of buildings nationally.
• The component risk fields themselves stay null in this case. More generally, a null component risk is structural, not missing data: each component only applies to certain foundation types (e.g. drystandRisk to wood foundations, dewateringDepthRisk to no-pile foundations). Do not infer data quality from individual null components.
• Report-derived unclassifiedRisk values always take precedence over the fallback.
• Consequently, the no_data_available error (§5) is rare in practice and mainly occurs for buildings not yet present in the current model snapshot, such as very recent BAG additions.
• Do not assert on this. The fallback is derived from the construction year, so a building whose construction year is itself unknown gets no fallback and returns null for all four risk fields. In the current snapshot that is exactly 1 building out of 11.2M — but it is not zero, so treat "all risks null" as a case your code handles rather than an impossible state.

7. Health check

GET /v4/health reports whether the webservice can currently serve product requests. It is unauthenticated, never billed, and intended for availability monitors.

curl -i https://ws.fundermaps.com/v4/health

Treat the HTTP status as the contract: 200 means available, anything else means unavailable. The body is informational and deliberately carries no technical detail (no versions, hostnames, or timings).

• Responses carry Cache-Control: no-store; every call reflects the current state.
• The state is re-evaluated at most once every 5 seconds server-side. Once a minute is a sensible polling interval; polling faster does not give fresher answers.
• A 200 says the service is available, not that a specific building has data — the 404 codes in §5 still apply to product calls.
• Staging exposes the same endpoint at https://ws-staging.fundermaps.com/v4/health.

Enum reference

The values below are the exact, complete label sets of the database enum types the API serves from — every value a v4 response can contain is listed, and a CI check keeps this table in sync with the implementation (src/enums.ts). All enum fields are nullable: expect null when the underlying data point is absent.

Correction notice (June 2026). Earlier revisions of this table were incomplete and listed four inquiryType values that the API never returns. If you implemented against an earlier revision, update your parsers:

• monitor → the API returns monitoring
• inspection → the API returns inspectionpit
• demolition → the API returns demolition_research
• quick_scan → the API returns quickscan

Additionally, 8 foundationType values, 5 damageCause values, and 4 further inquiryType values (archive_research, ground_water_level_research, soil_investigation, facade_scan) were missing and have been added above. Treat any enum value outside this table as a defect and report it to us.

Appendix: coming from v3

/api/v3 was retired on 2026-08-29. The data and its meaning did not change between v3 and v4 — the same building returns the same assessment — but the wire format did. This appendix exists so historical v3 output can be reconciled with v4; nothing in it is needed for a new integration.

• Paths: /api/v3/product/{analysis|statistics}/{id} → /v4/product/…/{id}. risk, light, facade_scan, foundation-research, usage, health and mcp have no v3 equivalent.
• Authentication: only Authorization: Bearer fmsk.…; X-API-Key, Authorization: authkey and ?authkey= are gone.
• Enums are strings, not integers — mapping tables below. Do not derive the mapping from the position of a value in the enum reference; that table follows the database ordering, which is not the v3 ordering.
• Analysis: enforcementTerm and overallQuality were removed (source column had drifted from the documented semantics); addressCount was added.
• Statistics: foundationTypeDistribution is the array itself (was { foundationTypes: [...] }); constructionYearDistribution items are { yearFrom, count } (was nested decade.yearFrom/yearTo dates + totalCount); foundationRiskDistribution is an array of { foundationRisk, percentage } (was percentageA–percentageE); the four year-count arrays renamed totalCount → count.
• Errors: every non-200 response is { code, message } with a stable code (§5).

Integer → string mapping

The underlying values did not change — only their encoding. A building that returned foundationType: 3 from v3 returns foundationType: "concrete" from v4 for the same identifier, from the same source data. Use these tables to reconcile historical v3 output with v4 output.

⚠️ Do not derive this mapping from the position of a value in the enum reference table. That table is ordered by the database's own enum ordering, which is not the v3 integer ordering. Mapping by position silently yields concrete where v3 said wood_amsterdam, and so on. Use the explicit tables below.

Reliability — applies to all *Reliability fields:

FoundationRisk — applies to drystandRisk, bioInfectionRisk, dewateringDepthRisk, unclassifiedRisk, and facadeScanRisk:

foundationType:

inquiryType:

recoveryType:

damageCause — note that 7 is not used; the v3 integer sequence has a gap there. Do not assume contiguous values.