# Quickstart

> From signing in to your first home value.

Source: https://huispedia.dev/en/docs/quickstart/

1. Sign in at [https://huispedia.dev/en/dashboard/signin/](https://huispedia.dev/en/dashboard/signin/) with your huispedia.nl or Pro account.
2. Choose your plan; Free is fine.
3. Create an API key (`hp_…`) under *API keys*. You see it once.
4. Value a home:

```bash
curl https://huispedia.dev/v5/properties/1076LJ-12-2/valuation \
  -H "X-API-Key: $HUISPEDIA_KEY"
```

<details class="hp-sample">
<summary>What the answer looks like</summary>

```json
{
  "address": {
    "bag_id": "0363200000028422", "postcode": "1076LJ", "house_number": 12, "house_number_ext": "2",
    "street": "Amazonenstraat", "city": "Amsterdam", "municipality": "Amsterdam", "province": "Noord-Holland",
    "location": { "lat": 52.34536032, "lon": 4.86274012 },
    "huispedia_url": "https://huispedia.nl/amsterdam/1076LJ/amazonenstraat/12-2"
  },
  "valuation": { "value": 888264, "lower": 838099, "upper": 941431, "interval": 0.8, "price_per_m2": 9064, "as_of_date": "2026-10-26", "model": "avm4", "model_version": "2026.10" },
  "confidence": { "score_pct": 90.3, "class": "high", "within_5_pct": 45.2, "within_10_pct": 90.3, "within_20_pct": 100.0 },
  "meta": { "request_id": "req_01M5W27EFJTGG4DQDJ6DVK3NVY", "as_of": "2026-10-26", "credits": { "charged": 8, "balance": 192 } }
}
```

`value` is the Huispedia home value; the actual value lies between `lower` and `upper` with 80% certainty.

</details>

## Next

- [Data catalogue](https://huispedia.dev/en/docs/catalogue/): what else you can ask for.
- [Endpoints](https://huispedia.dev/en/docs/endpoints/): every endpoint, to try with your own credits once signed in.
- [Addresses and areas](https://huispedia.dev/en/docs/locators/): point at a home by BAG id or at an area by CBS code.
- [Claude Code plugin](https://huispedia.dev/en/docs/claude/): let Claude Code write your calls.
- [Migrating from Altum](https://huispedia.dev/en/docs/migrate/altum/)
- [Migrating from Matrixian](https://huispedia.dev/en/docs/migrate/matrixian/)

---

# Data catalogue

> What each endpoint returns and what it costs.

Source: https://huispedia.dev/en/docs/catalogue/

Every endpoint with its credits, fields and sources is in the catalogue: [`GET https://huispedia.dev/v5/catalog`](https://huispedia.dev/v5/catalog) (JSON, no key needed) and the [OpenAPI document](https://huispedia.dev/openapi.json).

## Plans

Credits every month, cheaper than one by one. See [Credits and pricing](https://huispedia.dev/en/docs/credits/).

The plans with their prices and credits are under `packs` in [`GET https://huispedia.dev/v5/catalog`](https://huispedia.dev/v5/catalog).

## Migrate

- [From Altum](https://huispedia.dev/en/docs/migrate/altum/)
- [From Matrixian](https://huispedia.dev/en/docs/migrate/matrixian/)

---

# Authentication

> How to send your API key.

Source: https://huispedia.dev/en/docs/authentication/

Send your key in the header `X-API-Key: hp_…` or `Authorization: Bearer hp_…`, never in the URL.

- **You see a key once.** Lost it? Create a new one and revoke the old one.
- **Per key** you can set an expiry date and an IP allowlist.
- **A key belongs to one account**: your own, or a Pro organisation you manage. Switch in the dashboard.
- **`console`** in your request log is the temporary key of the endpoints page and the quickstart.

When your key does not work you get a `401` or `403`; the [error codes](https://huispedia.dev/en/docs/errors/) say why.

---

# Credits and pricing

> What a call costs and which credits go first.

Source: https://huispedia.dev/en/docs/credits/

Every endpoint costs a fixed number of credits. A credit is €0.05 excluding VAT; on the Free plan every user account gets 200 free credits a month.

Every endpoint with its credits, fields and sources is in the catalogue: [`GET https://huispedia.dev/v5/catalog`](https://huispedia.dev/v5/catalog) (JSON, no key needed) and the [OpenAPI document](https://huispedia.dev/openapi.json).

**What costs and what does not.** Only a successful answer (2xx) costs credits. A 404, a validation error or an outage costs nothing, and so does `HEAD`. In a scenario valuation you pay per successful row and per scenario.

**Which credits first.** Your free credits first, then your plan's, then your bought credits, oldest first. Bought credits are valid for 12 months; the dashboard shows each bundle's end date.

**Spend cap.** 2,000 bought credits (€100 excl. VAT) a month by default, on top of your free credits and your plan. Raise it under *Settings*; at the cap the API answers `402 spend_cap_reached`.

**Transactions.** Transaction prices come with a contract; contact [sales@huispedia.nl](mailto:sales@huispedia.nl). Kadaster transaction records in an answer count in `X-Kadaster-Records` and appear as their own line on your monthly statement.

## Plans

A paid plan gives you credits every month for a fixed price, cheaper than one by one. Plan credits you do not use expire at the end of the month. Credits you buy on top always cost €0.05 excluding VAT and are valid for 12 months, plan or not. A bigger discount comes with a bigger plan.

What an endpoint costs in credits is in the catalogue. If that changes, you hear it by email at least 30 days ahead.

The plans with their prices and credits are under `packs` in [`GET https://huispedia.dev/v5/catalog`](https://huispedia.dev/v5/catalog).

---

# Payments and invoices

> Plans, buying credits, auto top-up, invoices and refunds.

Source: https://huispedia.dev/en/docs/billing/

You buy credits under [Billing](https://huispedia.dev/en/dashboard/billing/), by credit card or iDEAL | Wero, between €10 and €5,000 at a time. A credit costs €0.05 excluding VAT. Bought credits are valid for 12 months.

**Plans.** Free is the plan without a subscription. You choose a paid plan under *Billing* and pay for it monthly by credit card. A bigger plan starts right away: you pay the difference for the rest of the month and get the extra credits. A smaller plan starts at the next renewal. You can cancel any time; your plan then runs until the end of the month, then you are on Free. If a renewal does not go through, we try again a few times and let you know. You get that month's credits as soon as the payment succeeds; if it never does, your plan ends.

**Auto top-up.** When your balance drops below a threshold you choose, we charge a fixed amount to your saved credit card, up to a monthly cap. After three failed charges, or when you remove the credit card, we switch it off and let you know.

**Invoices.** Amounts are excluding VAT; 21% VAT is added. Every payment gives an invoice with your billing details, your PO number if you fill one in, and the VAT. Under *Invoices* you find the invoice as a PDF and the receipt.

**Refunds.** A refund or chargeback takes the bought credits or plan credits off your balance again. What you had already spent shows as a negative balance; your next top-up covers it first. A chargeback suspends your account until it is resolved and ends your plan.

---

# Addresses and areas

> Pointing at a home or an area in the path.

Source: https://huispedia.dev/en/docs/locators/

## Homes

A home appears in the path as `:locator`, in one of two forms:

| Form | Example | What you pass |
|---|---|---|
| BAG nummeraanduiding | `bag:0363200000028422` | The 16-digit BAG id of the address |
| Postcode address | `1076LJ-12-2` | Postcode, house number and the extension when there is one; case and spaces do not matter |

Don't know the extension? `GET /v5/addresses/suggest?q=Amazonenstraat 12, Amsterdam` looks the address up (free); `GET /v5/addresses/1076LJ-12?all=true` returns every home at a house number.

In a POST body (scenario valuations) you identify a home with `locator`, `bag_id` or `postcode` + `house_number` (+ `house_number_ext`).

## Areas

An area appears in the path as `:area`, always as `level:code`:

| Level | Code | Example |
|---|---|---|
| `neighbourhood` | CBS neighbourhood code | `neighbourhood:BU0363KH05` |
| `district` | CBS district code | `district:WK0363KH` |
| `municipality` | CBS municipality code | `municipality:GM0363` |
| `province` | CBS province code | `province:PV27` |
| `postcode4` | The four digits of the postcode | `postcode4:1076` |
| `postcode6` | The full postcode | `postcode6:1076LJ` |
| `national` | No code | `national` |

The CBS codes are in every answer about an address, or look them up with `GET /v5/areas/lookup?postcode=1076LJ`. Statistics, the price index and demographics exist per neighbourhood, district, municipality, province and the whole country.

---

# Endpoints

> Every endpoint with its parameters and answers, ready to try.

Source: https://huispedia.dev/en/docs/endpoints/

Every endpoint with its parameters and answers: [OpenAPI 3.1](https://huispedia.dev/openapi.json) (Dutch: [https://huispedia.dev/openapi.nl.json](https://huispedia.dev/openapi.nl.json)). Try them with your own credits at [https://huispedia.dev/en/docs/endpoints/](https://huispedia.dev/en/docs/endpoints/) once signed in.

---

# Errors

> Every error code and what to do about it.

Source: https://huispedia.dev/en/docs/errors/

An error is `application/problem+json` (RFC 9457) with a fixed `code`; `detail` says in your `Accept-Language` what you can do. An error costs no credits.

```json
{
  "type": "https://huispedia.dev/en/docs/errors#insufficient_credits",
  "title": "Insufficient credits",
  "status": 402,
  "code": "insufficient_credits",
  "detail": "This call costs 8 credits; your balance is 3. Buy credits in the dashboard.",
  "request_id": "req_01M4…",
  "errors": []
}
```

| HTTP | `code` | When |
|---|---|---|
| 400 | `invalid_request` | The request is not right; `errors` says what is wrong per field |
| 401 | `unauthenticated` | Missing or unknown key |
| 401 | `key_revoked`, `key_expired` | Key revoked or expired |
| 402 | `insufficient_credits` | Your balance does not cover the call |
| 402 | `spend_cap_reached` | Your spend cap for this month is reached |
| 403 | `entitlement_required` | This endpoint is not part of your account |
| 403 | `ip_not_allowed` | IP address outside the key's allowlist |
| 403 | `account_suspended` | Account suspended |
| 403 | `forbidden` | This account may not do this |
| 404 | `not_found` | The locator finds nothing |
| 405 | `method_not_allowed` | This method does not exist on this path |
| 409 | `address_ambiguous` | Several homes at the address; `errors` carries the candidates |
| 409 | `conflict` | The action clashes with the current state; `detail` says how |
| 422 | `data_unavailable` | The home or area exists, but this data is not available for it |
| 429 | `rate_limited` | Per-key or per-account limit; see `Retry-After` |
| 503 | `upstream_unavailable` | Temporarily unavailable; see `Retry-After` |
| 503 | `billing_unavailable` | Payments are not possible right now |
| 500 | `internal_error` | A fault on our side; quote the `request_id` |

---

# Rate limits

> Calls per second per plan, and how long you may keep an answer.

Source: https://huispedia.dev/en/docs/rate-limits/

| Plan | Per second | At a time | Daily signal value |
|---|---|---|---|
| Free | 1 call, burst 5 | 2 | 500 calls |
| Starter, Growth, Scale, Pro | 6 calls, burst 20 | 6 | 20,000 calls |
| Enterprise | Per agreement | Per agreement | Per agreement |

The per-second limit is for your whole account, all your keys together. With a running plan or a purchase in the last 12 months you have the paid plans' limits. Free is for building and testing your integration.

The signal value is not a hard limit. If your calls stay above it for a while, we get in touch and look for a plan that fits together ([fair use](https://huispedia.dev/en/voorwaarden/#annex-b-fair-use-policy), Annex B).

Every answer carries `X-RateLimit-Remaining` and `X-RateLimit-Reset`; on `429 rate_limited` wait `Retry-After` seconds.

`Cache-Control` says per endpoint how long you may reuse an answer: valuations not at all, characteristics an hour, area statistics a day. In any case, keep Output no longer than 30 days, unless it belongs to an ongoing file about one home.

---

# Changelog

> What changes. Within v5, fields and endpoints are only added.

Source: https://huispedia.dev/en/docs/changelog/

Within v5, fields and endpoints are only added; what you use now keeps working. See [Versioning](https://huispedia.dev/en/docs/versioning/).

## 2026-10

- **New:** the v5 API with 21 endpoints: addresses, property characteristics, energy label, WOZ, building, condition, transactions, valuation, valuation plus, reference homes, valuation history, scenario valuations, areas, statistics, price index, demographics, surroundings and environment.
- **New:** the dashboard: sign in with your huispedia.nl account, keys, balance, usage and request log.

---

# Versioning

> What may change within v5, and what never does.

Source: https://huispedia.dev/en/docs/versioning/

Within v5 every change is an addition:

- new endpoints;
- new optional parameters and request fields;
- new fields in an answer;
- new values in a list of values, such as a new `house_type` or error `code`.

Nothing is removed, renamed, made required or made stricter. Code that works today keeps working, provided it ignores fields it does not know and accepts values it has not seen.

A change that would break that comes only in a new major version (v6). We announce it at least 60 days ahead, by email and in the [changelog](https://huispedia.dev/en/docs/changelog/) ([API terms](https://huispedia.dev/en/voorwaarden/), art. 11.2). v5 keeps running next to it for a period we state there.

---

# Claude Code plugin

> Skills that teach Claude Code this API and the move from Altum or Matrixian.

Source: https://huispedia.dev/en/docs/claude/

The plugin `huispedia-api` gives Claude Code three skills:

- **`huispedia-api`**: keys, addresses and areas, endpoints, credits, rate limits and errors.
- **`migrate-from-altum`**: moves code from Altum to this API, endpoint by endpoint and field by field.
- **`migrate-from-matrixian`**: the same for Matrixian.

Claude picks a skill by itself when your question or your code calls for it. The skills hold no key: your code reads yours from the environment, for example `HUISPEDIA_KEY`.

## Install

In Claude Code:

```
/plugin marketplace add Housepedia/claude-plugins
/plugin install huispedia-api@Huispedia
```

From the shell:

```bash
claude plugin marketplace add Housepedia/claude-plugins
claude plugin install huispedia-api@Huispedia
```

## Updates

The skills are built from these docs, so they change when the docs do. Update with `/plugin marketplace update Huispedia`, or turn on auto-update for the marketplace under `/plugin`.

## Other AI tools

Every page of these docs is also Markdown: add `.md` to its URL, for example [/en/docs/quickstart.md](https://huispedia.dev/en/docs/quickstart.md). [/llms.txt](https://huispedia.dev/llms.txt) lists the pages; [/llms-full.txt](https://huispedia.dev/llms-full.txt) has all English docs in one file, [/nl/llms-full.txt](https://huispedia.dev/nl/llms-full.txt) the Dutch. Every endpoint is in [/openapi.json](https://huispedia.dev/openapi.json).

---

# Migrating from Altum

> What you do on Altum and how you do it here.

Source: https://huispedia.dev/en/docs/migrate/altum/

Based on Altum's public documentation, October 2026.

Using Claude Code? The `migrate-from-altum` skill moves your code over with these tables; see the [Claude Code plugin](https://huispedia.dev/en/docs/claude/).

## Endpoints

| Altum | What | Huispedia |
|---|---|---|
| `POST /avm`, `POST /v2/avm` | Home valuation | [`GET /v5/properties/{locator}/valuation`](https://huispedia.dev/en/docs/endpoints/#tag/valuations/GET/v5/properties/{locator}/valuation) |
| `POST /avm` with your own characteristics | Valuation with your own inputs | [`POST /v5/valuations/scenarios`](https://huispedia.dev/en/docs/endpoints/#tag/valuations/POST/v5/valuations/scenarios) |
| `POST /avm/bulk` | Bulk valuation | [`POST /v5/valuations/scenarios`](https://huispedia.dev/en/docs/endpoints/#tag/valuations/POST/v5/valuations/scenarios)<br>Up to 100 homes per call, answered at once. |
| `POST /avmplus` | Home valuation plus | [`GET /v5/properties/{locator}/valuation/plus`](https://huispedia.dev/en/docs/endpoints/#tag/valuations/GET/v5/properties/{locator}/valuation/plus) (contract) |
| `POST /v2/objectdata` | Property characteristics | [`GET /v5/properties/{locator}`](https://huispedia.dev/en/docs/endpoints/#tag/properties/GET/v5/properties/{locator}) |
| `POST /interactive-reference` | Reference homes | [`GET /v5/properties/{locator}/references`](https://huispedia.dev/en/docs/endpoints/#tag/valuations/GET/v5/properties/{locator}/references) (contract) |
| `POST /v2/transaction` | Transactions | [`GET /v5/properties/{locator}/transactions`](https://huispedia.dev/en/docs/endpoints/#tag/properties/GET/v5/properties/{locator}/transactions) (contract) |
| `POST /v2/transaction/ping` | Any transactions? | [`HEAD /v5/properties/{locator}/transactions`](https://huispedia.dev/en/docs/endpoints/#tag/properties/HEAD/v5/properties/{locator}/transactions) |
| `POST /woz`, `GET /woz` | WOZ value | [`GET /v5/properties/{locator}/woz`](https://huispedia.dev/en/docs/endpoints/#tag/properties/GET/v5/properties/{locator}/woz) |
| `GET /market-trend` | Market trend | [`GET /v5/areas/{area}/stats`](https://huispedia.dev/en/docs/endpoints/#tag/areas-and-market/GET/v5/areas/{area}/stats)<br>[`GET /v5/areas/{area}/trends`](https://huispedia.dev/en/docs/endpoints/#tag/areas-and-market/GET/v5/areas/{area}/trends) |
| `POST /location-data` | Location data | [`GET /v5/addresses/{locator}`](https://huispedia.dev/en/docs/endpoints/#tag/addresses/GET/v5/addresses/{locator})<br>[`GET /v5/areas/{area}/demographics`](https://huispedia.dev/en/docs/endpoints/#tag/areas-and-market/GET/v5/areas/{area}/demographics) |
| `GET /autosuggest/v2`, `GET /autosearch` | Address search | [`GET /v5/addresses/suggest`](https://huispedia.dev/en/docs/endpoints/#tag/addresses/GET/v5/addresses/suggest) |
| `POST /condition-score/{img,url}` | Condition score | [`GET /v5/properties/{locator}/condition`](https://huispedia.dev/en/docs/endpoints/#tag/properties/GET/v5/properties/{locator}/condition)<br>Per address; you do not send your own photos. |
| `GET /credit` | Usage | [`GET /v5/account/usage`](https://huispedia.dev/en/docs/endpoints/#tag/account/GET/v5/account/usage) |

Transactions, reference homes and home valuation plus come with a contract: [sales@huispedia.nl](mailto:sales@huispedia.nl).

## Authentication

|  | Altum | Huispedia |
|---|---|---|
| **Key** | `x-api-key: <key>` | `X-API-Key: hp_…` or `Authorization: Bearer hp_…` |
| **Base URL** | `https://api.altum.ai` | `https://huispedia.dev/v5` |
| **Method** | `POST` with a JSON body | `GET` with the home in the path; `POST` only for scenarios |
| **Testing** | `/sandbox/` in the path | No sandbox: you test with your free credits or on the [Endpoints](https://huispedia.dev/en/docs/endpoints/) page |

## Addresses and areas

| Altum | Huispedia | Note |
|---|---|---|
| `postcode` + `housenumber` + `houseaddition` | `1076LJ-12-2` | Postcode, number and extension with hyphens in the path. |
| `houseaddition` (`A02`, `2B`) | `-A02`, `-2B` | Not sure: `GET /v5/addresses/1076LJ-12?all=true` returns every home with its `house_number_ext`. |
| `bag_id` (verblijfsobject) | `bag:0363200000028422` (nummeraanduiding) | The verblijfsobject id is `bag_verblijfsobject_id` in `GET /v5/addresses/{locator}`. |
| `valuationdate` (`20260901`) | `as_of_date` (`2026-09-01`) |  |
| `postcode` (Markttrend) | `neighbourhood:BU0363KH05` | An area is `level:code`; `GET /v5/areas/lookup?postcode=1076LJ` gives the codes. |

More in [Addresses and areas](https://huispedia.dev/en/docs/locators/).

## Fields

### Home valuation

`POST /avm` → [`GET /v5/properties/{locator}/valuation`](https://huispedia.dev/en/docs/endpoints/#tag/valuations/GET/v5/properties/{locator}/valuation)

| Altum | Huispedia | Note |
|---|---|---|
| `postcode`, `housenumber`, `houseaddition` | `{locator}` |  |
| `valuationdate` | `?as_of_date=` | Up to six months back; further back with the valuation history. |
| `Output.PriceEstimation` | `valuation.value` | A number, not a string. |
| `Output.Confidence` | `valuation.lower`, `valuation.upper`, `valuation.interval` | There a 90% interval in one string; here an 80% interval in two numbers. |
| `Output.AccuracyIndicator` | `confidence.class`, `confidence.score_pct`, `confidence.within_10_pct` | There a class 0 to 7; here `high`, `medium` or `low` and percentages. |
| `Output.ValuationDate` | `valuation.as_of_date` |  |
| `Output.BagID`, `PostCode`, `HouseNumber`, `HouseAddition`, `Street`, `City` | `address.bag_id`, `address.postcode`, `address.house_number`, `address.house_number_ext`, `address.street`, `address.city` |  |
| `Output.Longitude`, `Latitude` | `address.location.lon`, `address.location.lat` |  |
| `Output.HouseType`, `BuildYear`, `InnerSurfaceArea`, `OuterSurfaceArea`, `Volume`, `EnergyLabel` | `type.house_type`, `construction.construction_year`, `dimensions.living_area_m2`, `dimensions.plot_area_m2`, `dimensions.volume_m3`, `energy.energy_label`<br>In [`GET /v5/properties/{locator}`](https://huispedia.dev/en/docs/endpoints/#tag/properties/GET/v5/properties/{locator}) | From Property characteristics. |
| `Output.Image` | *Not available here* |  |

### Valuation with your own characteristics

`POST /avm` → [`POST /v5/valuations/scenarios`](https://huispedia.dev/en/docs/endpoints/#tag/valuations/POST/v5/valuations/scenarios)

| Altum | Huispedia | Note |
|---|---|---|
| `postcode`, `housenumber`, `houseaddition` | `data[].postcode`, `data[].house_number`, `data[].house_number_ext` |  |
| `innersurfacearea` | `data[].living_area_m2` |  |
| `outersurfacearea` | `data[].plot_area_m2` |  |
| `buildyear` | `data[].construction_year` |  |
| `housetype` | `data[].house_type` | `terraced`, `corner`, `semi_detached`, `detached` or `apartment`. |
| `energylabel` | `data[].energy_label` |  |
| `Output.PriceEstimation` | `data[].valuation.value` |  |

### Property characteristics

`POST /v2/objectdata` → [`GET /v5/properties/{locator}`](https://huispedia.dev/en/docs/endpoints/#tag/properties/GET/v5/properties/{locator})

| Altum | Huispedia | Note |
|---|---|---|
| `house_type_generic`, `house_type_specific` | `type.object_type`, `type.house_type_detail` |  |
| `inner_surface_area`, `outer_surface_area`, `volume` | `dimensions.living_area_m2`, `dimensions.plot_area_m2`, `dimensions.volume_m3` |  |
| `build_year` | `construction.construction_year` |  |
| `rooms`, `number_of_bathrooms` | `rooms.rooms`, `rooms.bathrooms` |  |
| `garden_orientation`, `garden_size` | `outdoor.garden_orientation`, `outdoor.garden_area_m2` |  |
| `monument` | `construction.is_monument` |  |
| `longitude`, `latitude`, `municipality_name`, `province` | `address.location.lon`, `address.location.lat`, `address.municipality`, `address.province` |  |
| `neighbourhood_code`, `municipality_code` | `neighbourhood.code`, `municipality_code`<br>In [`GET /v5/addresses/{locator}`](https://huispedia.dev/en/docs/endpoints/#tag/addresses/GET/v5/addresses/{locator}) |  |
| `ozb_tax`, `waste_tax_*`, `sewage_tax_*` | *Not available here* |  |

### Reference homes

`POST /interactive-reference` → [`GET /v5/properties/{locator}/references`](https://huispedia.dev/en/docs/endpoints/#tag/valuations/GET/v5/properties/{locator}/references)

| Altum | Huispedia | Note |
|---|---|---|
| `reference_number` | `?limit=` | 3 to 30. |
| `date_limit` | `?max_age_months=` |  |
| `housetype_to_search`, `strict_*`, `comparable_*` | `?same_type=`, `?max_distance_m=`, `?min_living_area_m2=`, `?max_living_area_m2=`, `?min_construction_year=`, `?max_construction_year=` | Bounds instead of levels. |
| `weight_*` | `?sort=` | Sort by `similarity`, `distance` or `date`; no weights of your own. |
| `GivenHouse` | `target` |  |
| `ReferenceHouses[]` | `data[]` |  |
| `Distance`, `Transactiondate`, `Source` | `data[].distance_m`, `data[].transaction_date`, `data[].source` |  |
| `TransactionPrice`, `IndexedTransactionPrice` | `data[].price`, `data[].price_indexed` |  |
| `InnerSurfaceArea`, `BuildYear`, `HouseType` | `data[].living_area_m2`, `data[].construction_year`, `data[].house_type` |  |
| `Weight` | *Not available here* |  |
| `VisualSimilarityScore`, `ReferencePriceMean` | *Not available here* |  |

### Transactions

`POST /v2/transaction` → [`GET /v5/properties/{locator}/transactions`](https://huispedia.dev/en/docs/endpoints/#tag/properties/GET/v5/properties/{locator}/transactions)

| Altum | Huispedia | Note |
|---|---|---|
| `valuation_date` | *Not available here* | You get every sale of the home; filter on `transaction_date` yourself. |
| `transaction`, `transaction_date` | `data[].transaction_id`, `data[].transaction_date` |  |
| `transaction_price`, `transaction_price_indexed` | `data[].price`, `data[].price_indexed` |  |
| `buyer`, `seller`, `family_transaction`, `more_real_estate`, `business_right` | *Not available here* |  |

### WOZ value

`POST /woz` → [`GET /v5/properties/{locator}/woz`](https://huispedia.dev/en/docs/endpoints/#tag/properties/GET/v5/properties/{locator}/woz)

| Altum | Huispedia | Note |
|---|---|---|
| `index: 1` | `?index=` |  |
| `wozvalue[].Date`, `Value`, `IndexedValue` | `values[].reference_date`, `values[].value`, `values[].indexed_value` |  |

### Market trend

`GET /market-trend` → [`GET /v5/areas/{area}/stats`](https://huispedia.dev/en/docs/endpoints/#tag/areas-and-market/GET/v5/areas/{area}/stats)

| Altum | Huispedia | Note |
|---|---|---|
| `postcode` | `{area}` | Codes from `GET /v5/areas/lookup?postcode=`. |
| `averagePriceSingleFamilyHomes`, `averagePriceMultiFamilyHomes` | `market.avg_transaction_price` | Not split by home type. |
| `pricePerSquareMeterSingleFamily`, `pricePerSquareMeterMultiFamily` | `market.avg_transaction_price_per_m2` |  |
| `annualPriceChange` | `market.transaction_price_per_m2_yoy_pct` |  |
| `transactionData.totalSalesLast12Months` | `market.transactions_count` |  |
| `fiveYearPriceChange` | `data[].value`, `data[].yoy_pct`<br>In [`GET /v5/areas/{area}/trends`](https://huispedia.dev/en/docs/endpoints/#tag/areas-and-market/GET/v5/areas/{area}/trends) | Price per m² per month, five years back by default. |

## Errors

An error is `application/problem+json` with a fixed `code`; every code is on [Errors](https://huispedia.dev/en/docs/errors/).

| Altum | Huispedia | Note |
|---|---|---|
| `400` (address not found) | [`404 not_found`](https://huispedia.dev/en/docs/errors/#not_found) |  |
| `400` (date format, house type), `422` (validation) | [`400 invalid_request`](https://huispedia.dev/en/docs/errors/#invalid_request) | `errors` names what is wrong per field. |
| `400` (no prediction possible) | [`422 data_unavailable`](https://huispedia.dev/en/docs/errors/#data_unavailable) |  |
| `401`, `403` (`Missing Authentication Token`) | [`401 unauthenticated`](https://huispedia.dev/en/docs/errors/#unauthenticated) |  |
| `403` (`Forbidden`, no access to the API) | [`403 entitlement_required`](https://huispedia.dev/en/docs/errors/#entitlement_required) |  |
| `429` (limit) | [`429 rate_limited`](https://huispedia.dev/en/docs/errors/#rate_limited) | Wait `Retry-After` seconds. |
| `429` (quota) | [`402 insufficient_credits`](https://huispedia.dev/en/docs/errors/#insufficient_credits), [`402 spend_cap_reached`](https://huispedia.dev/en/docs/errors/#spend_cap_reached) |  |
| `500` | [`500 internal_error`](https://huispedia.dev/en/docs/errors/#internal_error) |  |
| `{"Output": "…"}`, `{"detail": […]}` | `application/problem+json` with `code`, `detail`, `errors` |  |

## Bulk and limits

|  | Altum | Huispedia |
|---|---|---|
| **Rate** | Fair use: up to 6 concurrent requests per second | [6 per second and 6 at once on a paid plan; 1 and 2 on Free](https://huispedia.dev/en/docs/rate-limits/) |
| **Bulk** | `POST /avm/bulk`, then fetch the job | `POST /v5/valuations/scenarios`: 100 homes per call, answered at once |
| **Usage** | `GET /credit` | `GET /v5/account/usage` |

## Example: home valuation

**Altum**

```bash
curl -X POST https://api.altum.ai/avm \
  -H "x-api-key: $ALTUM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"postcode": "1076LJ", "housenumber": 12, "houseaddition": "2"}'
```

```python
import os, requests

r = requests.post(
    "https://api.altum.ai/avm",
    headers={"x-api-key": os.environ["ALTUM_KEY"]},
    json={"postcode": "1076LJ", "housenumber": 12, "houseaddition": "2"},
)
value = int(r.json()["Output"]["PriceEstimation"])
```

**Huispedia**

```bash
curl https://huispedia.dev/v5/properties/1076LJ-12-2/valuation \
  -H "X-API-Key: $HUISPEDIA_KEY"
```

```python
import os, requests

r = requests.get(
    "https://huispedia.dev/v5/properties/1076LJ-12-2/valuation",
    headers={"X-API-Key": os.environ["HUISPEDIA_KEY"]},
)
r.raise_for_status()
v = r.json()["valuation"]
value, lower, upper = v["value"], v["lower"], v["upper"]
```

## Differences

### Not available here

- Photo with the valuation (`image`): not available here.
- Pointing at a home by verblijfsobject id: not available here; use the nummeraanduiding.
- A valuation more than six months back: not available here; the valuation history gives one value per month.
- Your own weights, a weight per reference home and visual similarity: not available here; the order gives the likeness.
- Buyer, seller and Kadaster codes with transactions: not available here.
- Municipal charges (`ozb_tax` and the like): not available here.
- Average WOZ per postcode (`/woz/pc6`): not available here.
- Rental comparables, WWS points, rebuild and contents value: not available here.
- NTA 8800 label calculation, sustainability, subsidies, roof scans, EPC: not available here; `GET /v5/properties/{locator}/energy-label` gives the registered label.
- Move data, building geometry, photo labelling: not available here.

### No equivalent at Altum

- `409 address_ambiguous` with the candidates when an address has several homes: no equivalent at Altum.
- What-if scenarios against the same base (`scenarios`): no equivalent at Altum.
- Monthly valuation history in one call: no equivalent at Altum.
- Environment (foundation, subsidence, noise, air) and amenities per address: no equivalent in Altum's public documentation.
- A building with all its addresses (`/v5/buildings/{bag_pand_id}`): no equivalent in Altum's public documentation.

## Sources

- [Woningwaarde API](https://docs.altum.ai/taxeren-en-waarderen/woningwaarde-api/authentication-input-and-response)
- [Woningwaarde API, huisnummers en toevoegingen](https://docs.altum.ai/taxeren-en-waarderen/woningwaarde-api/house-numbers-and-additions)
- [Woningwaarde API, accuratesse-indicator](https://docs.altum.ai/taxeren-en-waarderen/woningwaarde-api/accuratesse-indicator)
- [Woningwaarde API, OpenAPI](https://api.altum.ai/avm/openapi)
- [Woningwaarde+ API](https://docs.altum.ai/taxeren-en-waarderen/woningwaarde+-api/authenticatie-invoer-en-resultaat)
- [Woningkenmerken API](https://docs.altum.ai/woningdata/woningkenmerken-api/authenticatie-invoer-en-resultaat)
- [Interactieve woningreferentie API](https://docs.altum.ai/taxeren-en-waarderen/interactieve-woningreferentie-api/authenticatie-invoer-en-resultaat)
- [Kadaster Transactie API](https://docs.altum.ai/taxeren-en-waarderen/kadaster-transactie-api/authenticatie-invoer-en-resultaat)
- [WOZ API](https://docs.altum.ai/woningdata/woz-api/authentication-input-and-response)
- [Markttrend API](https://docs.altum.ai/taxeren-en-waarderen/markttrend-api/authentication-input-and-response)
- [Sandbox](https://docs.altum.ai/ontwikkelaars/sandbox)
- [Fair use policy](https://docs.altum.ai/enterprise/fair-use-policy)
- [Foutcodes 403, 422, 429](https://docs.altum.ai/api-error-codes/422)
- [Verbruik API](https://docs.altum.ai/ontwikkelaars/verbruik-api)

---

# Migrating from Matrixian

> What you do on Matrixian and how you do it here.

Source: https://huispedia.dev/en/docs/migrate/matrixian/

Based on Matrixian's public documentation, October 2026.

Using Claude Code? The `migrate-from-matrixian` skill moves your code over with these tables; see the [Claude Code plugin](https://huispedia.dev/en/docs/claude/).

## Endpoints

| Matrixian | What | Huispedia |
|---|---|---|
| `GET /homevalue`, `GET /homevalue/value` | Home valuation | [`GET /v5/properties/{locator}/valuation`](https://huispedia.dev/en/docs/endpoints/#tag/valuations/GET/v5/properties/{locator}/valuation) |
| `GET /homevalue` with your own characteristics | Valuation with your own inputs | [`POST /v5/valuations/scenarios`](https://huispedia.dev/en/docs/endpoints/#tag/valuations/POST/v5/valuations/scenarios) |
| `GET /homevalue?nReferences=` | Valuation with references | [`GET /v5/properties/{locator}/valuation/plus`](https://huispedia.dev/en/docs/endpoints/#tag/valuations/GET/v5/properties/{locator}/valuation/plus) (contract)<br>With the five best reference homes. |
| `GET /leadtool` | Value range | [`GET /v5/properties/{locator}/valuation`](https://huispedia.dev/en/docs/endpoints/#tag/valuations/GET/v5/properties/{locator}/valuation)<br>The range is `lower` to `upper`. |
| `GET /mx-reference-finder` | Reference homes | [`GET /v5/properties/{locator}/references`](https://huispedia.dev/en/docs/endpoints/#tag/valuations/GET/v5/properties/{locator}/references) (contract) |
| `GET /mx-transaction-finder` | Sale price | [`GET /v5/properties/{locator}/transactions`](https://huispedia.dev/en/docs/endpoints/#tag/properties/GET/v5/properties/{locator}/transactions) (contract) |
| `GET /woz-value`, `GET /woz-value/live` | WOZ value | [`GET /v5/properties/{locator}/woz`](https://huispedia.dev/en/docs/endpoints/#tag/properties/GET/v5/properties/{locator}/woz) |
| `GET /mx-house-details` | Property characteristics | [`GET /v5/properties/{locator}`](https://huispedia.dev/en/docs/endpoints/#tag/properties/GET/v5/properties/{locator})<br>[`GET /v5/properties/{locator}/energy-label`](https://huispedia.dev/en/docs/endpoints/#tag/properties/GET/v5/properties/{locator}/energy-label) |
| `GET /bag-data` | BAG data | [`GET /v5/addresses/{locator}`](https://huispedia.dev/en/docs/endpoints/#tag/addresses/GET/v5/addresses/{locator})<br>[`GET /v5/buildings/{bag_pand_id}`](https://huispedia.dev/en/docs/endpoints/#tag/properties/GET/v5/buildings/{bag_pand_id}) |
| `GET /buurtinfo` | Neighbourhood information | [`GET /v5/areas/{area}/demographics`](https://huispedia.dev/en/docs/endpoints/#tag/areas-and-market/GET/v5/areas/{area}/demographics)<br>[`GET /v5/areas/{area}/stats`](https://huispedia.dev/en/docs/endpoints/#tag/areas-and-market/GET/v5/areas/{area}/stats)<br>[`GET /v5/areas/{area}`](https://huispedia.dev/en/docs/endpoints/#tag/areas-and-market/GET/v5/areas/{area}) |

Transactions, reference homes and home valuation plus come with a contract: [sales@huispedia.nl](mailto:sales@huispedia.nl).

## Authentication

|  | Matrixian | Huispedia |
|---|---|---|
| **Key** | `Authorization: Bearer <api-key>` | `Authorization: Bearer hp_…` or `X-API-Key: hp_…` |
| **Base URL** | `https://api.matrixian.com/v1` | `https://huispedia.dev/v5` |
| **Method** | `GET` with query parameters | `GET` with the home in the path; `POST` only for scenarios |
| **Response** | `{id, params, data, error, meta, status}` | The data at the top level; `meta` with `request_id` and `credits` |

## Addresses and areas

| Matrixian | Huispedia | Note |
|---|---|---|
| `postalCode` + `houseNumber` + `houseLetter` + `houseNumberExt` | `1076LJ-12-2` | Postcode, number and extension with hyphens in the path; letter and extension go together in the last part. |
| `houseLetter`, `houseNumberExt` | `house_number_ext` | Not sure: `GET /v5/addresses/1076LJ-12?all=true` returns every home with its `house_number_ext`. |
| `bagId`, `bagNumberId` (nummeraanduiding) | `bag:0363200000028422` |  |
| `bagObjectId`, `bagBuildingId` | `bag_verblijfsobject_id`, `bag_pand_id` | In `GET /v5/addresses/{locator}`; ask for a building with `GET /v5/buildings/{bag_pand_id}`. |
| `valuationDate` (`2026-09-01`) | `as_of_date` (`2026-09-01`) |  |
| `buurtCode` (`BU04170328`) | `neighbourhood:BU04170328` | An area is `level:code`; `GET /v5/areas/lookup?postcode=1076LJ` gives the codes. |

More in [Addresses and areas](https://huispedia.dev/en/docs/locators/).

## Fields

### Home valuation

`GET /homevalue` → [`GET /v5/properties/{locator}/valuation`](https://huispedia.dev/en/docs/endpoints/#tag/valuations/GET/v5/properties/{locator}/valuation)

| Matrixian | Huispedia | Note |
|---|---|---|
| `postalCode`, `houseNumber`, `houseLetter`, `houseNumberExt` | `{locator}` |  |
| `valuationDate` | `?as_of_date=` | Up to six months back; further back with the valuation history. |
| `data.predictedValue`, `data.weightedValue` | `valuation.value` |  |
| `data.valueDate` | `valuation.as_of_date` |  |
| `data.accuracy` | `confidence.score_pct` | Here the probability that the value is within 10% of a sale price. |
| `data.confidenceClass` | `confidence.class` | There 0 to 5; here `high`, `medium` or `low`. |
| `data.weightedValueRange` (Leadtool) | `valuation.lower`, `valuation.upper`, `valuation.interval` | Two numbers with their certainty (80%). |
| `data.bagId`, `postalCode`, `houseNumber`, `houseNumberExt`, `street`, `city`, `municipality` | `address.bag_id`, `address.postcode`, `address.house_number`, `address.house_number_ext`, `address.street`, `address.city`, `address.municipality` |  |
| `data.buildType`, `buildYear`, `useSurface`, `parcelSurface`, `volume`, `energyLabel`, `rooms` | `type.house_type`, `construction.construction_year`, `dimensions.living_area_m2`, `dimensions.plot_area_m2`, `dimensions.volume_m3`, `energy.energy_label`, `rooms.rooms`<br>In [`GET /v5/properties/{locator}`](https://huispedia.dev/en/docs/endpoints/#tag/properties/GET/v5/properties/{locator}) | From Property characteristics. |
| `data.indexedPrice`, `histTransactionPrice`, `histTransactionDate` | `data[].price_indexed`, `data[].price`, `data[].transaction_date`<br>In [`GET /v5/properties/{locator}/transactions`](https://huispedia.dev/en/docs/endpoints/#tag/properties/GET/v5/properties/{locator}/transactions) | Every sale of the home, with a contract. |
| `data.references[]` | `references[]`<br>In [`GET /v5/properties/{locator}/valuation/plus`](https://huispedia.dev/en/docs/endpoints/#tag/valuations/GET/v5/properties/{locator}/valuation/plus) |  |
| `data.numZip*`, `medZip*`, `numStr*`, `medStr*` | `market.transactions_count`, `market.avg_transaction_price`<br>In [`GET /v5/areas/{area}/stats`](https://huispedia.dev/en/docs/endpoints/#tag/areas-and-market/GET/v5/areas/{area}/stats) | Per neighbourhood, district or municipality; not per postcode or street. |

### Valuation with your own characteristics

`GET /homevalue` → [`POST /v5/valuations/scenarios`](https://huispedia.dev/en/docs/endpoints/#tag/valuations/POST/v5/valuations/scenarios)

| Matrixian | Huispedia | Note |
|---|---|---|
| `postalCode`, `houseNumber`, `houseNumberExt` | `data[].postcode`, `data[].house_number`, `data[].house_number_ext` |  |
| `useSurface` | `data[].living_area_m2` |  |
| `parcelSurface`, `volume` | `data[].plot_area_m2`, `data[].volume_m3` |  |
| `buildYear`, `numberOfRooms` | `data[].construction_year`, `data[].rooms` |  |
| `buildType` | `data[].house_type` | `terraced`, `corner`, `semi_detached`, `detached` or `apartment`. |
| `energyLabel` | `data[].energy_label` |  |
| `monument` | *Not available here* |  |
| `data.predictedValue` | `data[].valuation.value` |  |

### Property characteristics

`GET /mx-house-details` → [`GET /v5/properties/{locator}`](https://huispedia.dev/en/docs/endpoints/#tag/properties/GET/v5/properties/{locator})

| Matrixian | Huispedia | Note |
|---|---|---|
| `objectType` | `type.object_type` |  |
| `buildYear` | `construction.construction_year` |  |
| `livingSurface`, `useSurface` | `dimensions.living_area_m2`, `dimensions.bag_area_m2` |  |
| `otherIndoorSpace`, `attachedOutdoorSpace`, `externalStorageSpace` | `dimensions.other_indoor_m2`, `dimensions.building_bound_outdoor_m2`, `dimensions.external_storage_m2` |  |
| `parcelSurface`, `volume` | `dimensions.plot_area_m2`, `dimensions.volume_m3` |  |
| `numberOfRooms`, `numberOfBedrooms`, `numberOfBathrooms`, `numberOfToilets` | `rooms.rooms`, `rooms.bedrooms`, `rooms.bathrooms`, `rooms.separate_toilets` |  |
| `energyLabel` | `energy.energy_label` |  |
| `energyLabelRegistrationValidUntil` | `valid_to`<br>In [`GET /v5/properties/{locator}/energy-label`](https://huispedia.dev/en/docs/endpoints/#tag/properties/GET/v5/properties/{locator}/energy-label) |  |
| `latitude`, `longitude` | `address.location.lat`, `address.location.lon` |  |
| `bagObjectId`, `bagBuildingId`, neighbourhood and municipality codes | `bag_verblijfsobject_id`, `bag_pand_id`, `neighbourhood.code`, `municipality_code`<br>In [`GET /v5/addresses/{locator}`](https://huispedia.dev/en/docs/endpoints/#tag/addresses/GET/v5/addresses/{locator}) |  |
| `description` | *Not available here* |  |

### Reference homes

`GET /mx-reference-finder` → [`GET /v5/properties/{locator}/references`](https://huispedia.dev/en/docs/endpoints/#tag/valuations/GET/v5/properties/{locator}/references)

| Matrixian | Huispedia | Note |
|---|---|---|
| `nReferences` | `?limit=` | 3 to 30. |
| `valuationDate` | `?as_of_date=` |  |
| `maxDistance`, `minTransportDate` | `?max_distance_m=`, `?max_age_months=` |  |
| `minUseSurface`, `maxUseSurface` | `?min_living_area_m2=`, `?max_living_area_m2=` |  |
| `minBuildYear`, `maxBuildYear` | `?min_construction_year=`, `?max_construction_year=` |  |
| `allowedHouseTypes` | `?same_type=` | Only the same type, or all types. |
| `locationWeight`, `houseDetailsWeight`, `transportDateWeight` | `?sort=` | Sort by `similarity`, `distance` or `date`; no weights of your own. |
| `references[]` | `data[]` |  |
| `distance`, `dateSale` | `data[].distance_m`, `data[].transaction_date` |  |
| `houseType`, `buildYear`, `useSurface` | `data[].house_type`, `data[].construction_year`, `data[].living_area_m2` |  |
| `referenceScore`, `locationScore`, `houseDetailsScore` | *Not available here* |  |
| `offeredPrice`, `imageFront`, `description` | *Not available here* |  |

### Transactions

`GET /mx-transaction-finder` → [`GET /v5/properties/{locator}/transactions`](https://huispedia.dev/en/docs/endpoints/#tag/properties/GET/v5/properties/{locator}/transactions)

| Matrixian | Huispedia | Note |
|---|---|---|
| `valuationDate`, `dateTransport` | *Not available here* | You get every sale of the home; filter on `transaction_date` yourself. |
| `saleDate`, `transportDate` | `data[].price_agreement_date`, `data[].transaction_date` |  |
| `transactionPrice` | `data[].price` |  |
| `transactionPriceIndexed` | `data[].price_indexed` | At today's price level. |

### WOZ value

`GET /woz-value` → [`GET /v5/properties/{locator}/woz`](https://huispedia.dev/en/docs/endpoints/#tag/properties/GET/v5/properties/{locator}/woz)

| Matrixian | Huispedia | Note |
|---|---|---|
| `wozValues[].valuationDate`, `wozValue` | `values[].reference_date`, `values[].value` |  |
| `characteristics` | `type`, `dimensions`, `construction`<br>In [`GET /v5/properties/{locator}`](https://huispedia.dev/en/docs/endpoints/#tag/properties/GET/v5/properties/{locator}) |  |

### Neighbourhood information

`GET /buurtinfo` → [`GET /v5/areas/{area}/demographics`](https://huispedia.dev/en/docs/endpoints/#tag/areas-and-market/GET/v5/areas/{area}/demographics)

| Matrixian | Huispedia | Note |
|---|---|---|
| `buurtCode` or an address | `{area}` | Codes from `GET /v5/areas/lookup?postcode=`. |
| `Bevolking` | `population`, `households`, `age` |  |
| `Wonen` | `stock`<br>In [`GET /v5/areas/{area}/stats`](https://huispedia.dev/en/docs/endpoints/#tag/areas-and-market/GET/v5/areas/{area}/stats) |  |
| `geometry` | `geometry`<br>In [`GET /v5/areas/{area}`](https://huispedia.dev/en/docs/endpoints/#tag/areas-and-market/GET/v5/areas/{area}) | With `include=geometry`. |
| `Inkomen`, `Energie`, `Criminaliteit` | *Not available here* |  |

## Errors

An error is `application/problem+json` with a fixed `code`; every code is on [Errors](https://huispedia.dev/en/docs/errors/).

| Matrixian | Huispedia | Note |
|---|---|---|
| `400` (`errors[].reason` is the parameter) | [`400 invalid_request`](https://huispedia.dev/en/docs/errors/#invalid_request) | `errors` names what is wrong per field. |
| `401` | [`401 unauthenticated`](https://huispedia.dev/en/docs/errors/#unauthenticated), [`401 key_revoked`](https://huispedia.dev/en/docs/errors/#key_revoked), [`401 key_expired`](https://huispedia.dev/en/docs/errors/#key_expired) |  |
| `403` (`access_denied`, `missing_subscription`) | [`403 entitlement_required`](https://huispedia.dev/en/docs/errors/#entitlement_required), [`403 forbidden`](https://huispedia.dev/en/docs/errors/#forbidden) |  |
| `403` (`rate_limit`) | [`429 rate_limited`](https://huispedia.dev/en/docs/errors/#rate_limited) | Here `429`; wait `Retry-After` seconds. |
| `404` (unknown address) | [`404 not_found`](https://huispedia.dev/en/docs/errors/#not_found) |  |
| `500` | [`500 internal_error`](https://huispedia.dev/en/docs/errors/#internal_error) |  |
| `503` | [`503 upstream_unavailable`](https://huispedia.dev/en/docs/errors/#upstream_unavailable) |  |
| `{id, status: "failure", error: {code, message, errors}}` | `application/problem+json` with `code`, `detail`, `errors`, `request_id` |  |

## Bulk and limits

|  | Matrixian | Huispedia |
|---|---|---|
| **Rate** | Not published; at the limit `403 rate_limit` | [6 per second and 6 at once on a paid plan; 1 and 2 on Free](https://huispedia.dev/en/docs/rate-limits/); `X-RateLimit-Remaining` in every response |
| **Bulk** | No bulk endpoint documented | `POST /v5/valuations/scenarios`: 100 homes per call |
| **Correlation** | `id`, `X-Amzn-Trace-Id` | `meta.request_id`, `request_id` |

## Example: home valuation

**Matrixian**

```bash
curl "https://api.matrixian.com/v1/homevalue?postalCode=1076LJ&houseNumber=12&houseNumberExt=2" \
  -H "Authorization: Bearer $MATRIXIAN_KEY"
```

```python
import os, requests

r = requests.get(
    "https://api.matrixian.com/v1/homevalue",
    headers={"Authorization": f"Bearer {os.environ['MATRIXIAN_KEY']}"},
    params={"postalCode": "1076LJ", "houseNumber": 12, "houseNumberExt": "2"},
)
value = r.json()["data"]["predictedValue"]
```

**Huispedia**

```bash
curl https://huispedia.dev/v5/properties/1076LJ-12-2/valuation \
  -H "Authorization: Bearer $HUISPEDIA_KEY"
```

```python
import os, requests

r = requests.get(
    "https://huispedia.dev/v5/properties/1076LJ-12-2/valuation",
    headers={"Authorization": f"Bearer {os.environ['HUISPEDIA_KEY']}"},
)
r.raise_for_status()
v = r.json()["valuation"]
value, lower, upper = v["value"], v["lower"], v["upper"]
```

## Differences

### Not available here

- Checking availability first (`/homevalue/available`): not available here; a `404 not_found` costs no credits.
- Monument status as valuation input (`monument`): not available here.
- Market figures per postcode or street (`numZip*`, `numStr*`): not available here; per neighbourhood instead.
- Your own weights and scores per reference home: not available here; the order gives the likeness.
- Income, energy and crime per neighbourhood: not available here.
- Housing costs (`/local-tax-energy-expenses`): not available here.
- Home photos (`/house-images`, `/get_front_view`): not available here.
- Cadastral objects and ownership extracts: not available here.
- Commercial transactions: not available here.

### No equivalent at Matrixian

- An interval with lower and upper bound on every valuation: no equivalent at Matrixian, except the Leadtool's range string.
- `409 address_ambiguous` with the candidates when an address has several homes: no equivalent at Matrixian.
- What-if scenarios and up to 100 homes per call: no equivalent at Matrixian.
- Monthly valuation history: no equivalent at Matrixian.
- Price index per area (`/v5/areas/{area}/trends`): no equivalent in Matrixian's public documentation.
- Environment (foundation, subsidence, noise, air) per address: no equivalent in Matrixian's public documentation.

## Sources

- [Matrixian API, OpenAPI](https://matrixian-api.s3.eu-west-3.amazonaws.com/openapi.yaml)
- [API-authenticatie](https://docs.matrixian.com/readme/api-authenticatie)
- [API-responsestructuur](https://docs.matrixian.com/readme/api-response-structuur)
- [API-foutmeldingen](https://docs.matrixian.com/readme/api-foutmeldingen)
- [Woningwaarde API](https://docs.matrixian.com/waarderen-en-taxeren/woningwaarde-api-1)
- [Woningwaarde API (alleen waarde)](https://docs.matrixian.com/waarderen-en-taxeren/woningwaarde-api)
- [Leadtool API](https://docs.matrixian.com/waarderen-en-taxeren/leadtool-api)
- [Referentiewoningen API](https://docs.matrixian.com/waarderen-en-taxeren/referentiewoningen-api)
- [Koopsom API](https://docs.matrixian.com/waarderen-en-taxeren/koopsom-api)
- [WOZ-waarde API](https://docs.matrixian.com/waarderen-en-taxeren/woz-waarde-api)
- [Woningkenmerken API](https://docs.matrixian.com/woningdata/woningkenmerken-api)
- [BAG API](https://docs.matrixian.com/woningdata/bag-api)
- [Buurtinfo API](https://docs.matrixian.com/woningdata/buurtinfo-api)

---

# API terms of use

> The terms for using the Huispedia Data Intelligence API, with Annex A (contract endpoints) and Annex B (fair use).

Source: https://huispedia.dev/en/voorwaarden/

<!-- A translation of the API terms on huispedia.nl/api-voorwaarden (the
     Huispedia.nl repo, resources/views/legal/api_terms.blade.php); keep the two in step. -->

**Last updated: 28 October 2026**

:::note
This is a translation. The [Dutch text on huispedia.nl](https://huispedia.nl/api-voorwaarden) is binding.
:::

These terms apply to every use of the Huispedia API through [huispedia.dev](https://huispedia.dev), in addition to the [General Terms of Huispedia](https://huispedia.nl/algemene-voorwaarden). How Huispedia handles personal data is set out in the [privacy policy](https://huispedia.nl/privacybeleid).

## 1. Definitions

**1.1** **API:** the Huispedia API that Housepedia B.V. (Chamber of Commerce 71325824, Keizersgracht 264, 1016 EV Amsterdam) offers through huispedia.dev.

**1.2** **Customer:** the natural person, legal entity or business that holds an API account. A **Business Customer** acts in the course of a trade or profession. A **Consumer** is a Customer who does not.

**1.3** **Output:** all data, valuations, scores and other results the API returns.

**1.4** **End Customer:** a customer of the Customer to whom the Customer shows Output as part of its own services.

**1.5** **Credits:** the unit for paid calls. **Plan credits** belong to a monthly plan. **Extra credits** are bought separately or through auto top-up.

**1.6** **Contract endpoints:** Home value+, Comparable homes, Transactions and any endpoint Huispedia later designates as such. Annex A applies to them.

**1.7** **Transaction data:** purchase prices and transaction dates of individual homes, whether they come from the Kadaster (Land Registry) or from agents and users connected to Huispedia.

**1.8** **Data Sources:** parties Huispedia obtains data from, such as the Kadaster, CBS, the operators of the BAG and agents and users connected to Huispedia.

## 2. Applicability and order of precedence

**2.1** These API terms supplement the General Terms of Huispedia for every use of the API.

**2.2** In case of conflict, this order applies: (a) a signed agreement, (b) Annex A, (c) these API terms and Annex B, (d) the General Terms.

**2.3** Purchasing or other terms of the Customer do not apply.

## 3. Account and API keys

**3.1** At sign-up the Customer states whether it is a Business Customer or a Consumer. A Business Customer provides a valid Chamber of Commerce (KvK) number or, as a foreign business, an equivalent trade register number and VAT number. Huispedia may check these details and refuse or end an account if they are incorrect. Anyone who signs up as a Consumer but acts in the course of a trade or profession counts as a Business Customer. Contract endpoints are only available to Business Customers (Annex A).

**3.2** The Customer keeps API keys secret. Keys do not belong in public code, apps or End Customers' browsers.

**3.3** The Customer is responsible for all calls made with its keys, including misuse by third parties, until the Customer informs Huispedia of that misuse.

**3.4** The Customer reports misuse or a leaked key immediately to [support@huispedia.nl](mailto:support@huispedia.nl). Huispedia may then revoke the key.

## 4. Licence

**4.1** For the term of the agreement, Huispedia grants the Customer a limited, non-exclusive, non-transferable and non-sublicensable right to use the API and the Output under these terms.

**4.2** For a Business Customer, the right applies only to the legal entity with the KvK number of the account; group companies need an account of their own. For a Consumer, the right applies only to them personally.

**4.3** All rights not expressly granted remain with Huispedia and its Data Sources.

## 5. Permitted use of Output

**5.1** The Customer may use Output in its own software, dashboards, CRM systems and customer portals.

**5.2** The Customer may show Output per property to End Customers as part of its own services, for example in an advisory report.

**5.3** The Customer may store (cache) Output for up to 30 days, unless Annex A prescribes a shorter period. Output that is part of a file or report about one property may be kept for as long as that file runs, but the Customer does not use it to build a database.

**5.4** The Customer credits Huispedia as the source wherever Output is visible. Where the API or the catalogue names a Data Source (such as CBS or Kadaster), the Customer credits that source too.

## 6. Not permitted

The Customer will not:

- resell or sublicense Output, or make it available to third parties as raw data;
- use Output to build or supplement its own database, dataset or data service;
- use Output for a product that competes with Huispedia, or to train, test or improve AI models;
- query the API systematically to collect a large part of the housing stock (scraping);
- pass on calls for parties without a contract of their own, for example through a public portal or proxy;
- get around limits, for example with several accounts or keys;
- use Output for direct marketing (such as unsolicited mail or telemarketing) or for profiling people;
- pose as Huispedia or a Data Source, or use their name or logo beyond the required source credit;
- probe or decompile the API or get around its security.

## 7. Credits and plans

**7.1** Only successful calls cost credits. A call is successful when the API returns a result (HTTP 2xx). Errors and calls without a result cost nothing.

**7.2** The number of credits per endpoint is listed in the [catalogue](https://huispedia.dev/en/docs/catalogue/) on huispedia.dev. Huispedia may change this with 30 days' notice by email.

**7.3** Plan credits are added at the start of each plan month and expire at the end of that month. They do not roll over.

**7.4** Extra credits, bought separately or through auto top-up, are valid for 12 months from the date of purchase. They expire earlier if the account ends.

**7.5** Calls are charged to plan credits first and then to extra credits, oldest first. The dashboard shows the balance and expiry date of each credit pack.

**7.6** Plans renew automatically every month. The Customer can cancel at any time; the cancellation takes effect at the end of the current month.

**7.7** Credits are never refunded, also not when they expire or the account ends.

**7.8** Huispedia may index its prices every year on 1 January by the CPI (all households) of CBS.

## 8. Auto top-up

**8.1** Auto top-up is off by default. The Customer switches it on and chooses a threshold, an amount per top-up and a monthly maximum.

**8.2** By switching it on, the Customer authorises Huispedia to charge the saved payment method through the payment provider whenever the balance drops below the threshold, up to the chosen monthly maximum.

**8.3** After every top-up the Customer receives a receipt by email.

**8.4** The Customer can switch auto top-up off at any time in the dashboard.

**8.5** If a payment fails, Huispedia may block paid calls until the balance is positive again.

## 9. Payment

**9.1** Prices for Business Customers are exclusive of VAT. Prices for Consumers are inclusive of VAT. Payment runs through Huispedia's payment provider.

**9.2** For Enterprise customers paying by invoice, the payment term of article 14.3 of the General Terms applies (14 days).

**9.3** The API supplies digital content: with each call the Customer receives data right away. A Consumer loses the right of withdrawal once delivery has started, if they expressly agreed beforehand to immediate delivery and stated that they thereby lose their right of withdrawal. Delivery starts as soon as the credits are added to the account. Huispedia confirms this by email after the order. If the supply nevertheless counts as a service, a Consumer who withdraws pays pro rata for what they have already used.

## 10. Free plan

**10.1** The Free plan is meant for testing and developing with the API. The Customer does not use it in production towards End Customers. Wherever Output is visible, the Customer states "Data: Huispedia".

**10.2** Lower limits apply to the Free plan. Huispedia may change or end the Free plan at any time.

**10.3** Contract endpoints are not available on the Free plan.

## 11. Availability and changes

**11.1** Huispedia does its best to keep the API available but gives no guarantee of availability. An SLA applies only if agreed in writing (Enterprise).

**11.2** Huispedia announces changes that break existing integrations at least 60 days in advance by email and in the [changelog](https://huispedia.dev/en/docs/changelog/). In case of an acute security or legal risk, this can be sooner.

**11.3** Huispedia may change or stop endpoints if a Data Source limits or ends its supply. If an endpoint stops for that reason, the Customer deletes the Output of that endpoint within 30 days at Huispedia's request.

## 12. Indicative nature

**12.1** Valuations and other Output are model-based and indicative (articles 3.5 and 11 of the General Terms). They are not an appraisal.

**12.2** The Customer does not present Output to End Customers as an appraisal and is itself responsible for its advice and decisions. The Customer states in its own terms, or in the report or view in which it shows Output, that the Output is indicative and not an appraisal.

## 13. Suspension

**13.1** Huispedia may limit or suspend access in case of a breach of these terms, overdue payment, a risk to the stability or security of the API, or when a Data Source demands it.

**13.2** If improper use is suspected, Huispedia first gets in touch, unless immediate action is needed.

## 14. Liability and indemnity

**14.1** Huispedia provides the API and the Output as they are ("as is"). Huispedia does not warrant the accuracy, completeness or currency of Output or of data from Data Sources.

**14.2** Huispedia is not liable for (a) indirect and consequential damage, (b) lost profit, revenue or savings, (c) loss of or damage to data, (d) reputational damage, (e) damage from decisions or advice based on Output, (f) damage from inaccurate or discontinued data from Data Sources, and (g) claims of End Customers.

**14.3** To the extent Huispedia is liable after all, its total liability towards the Customer, on whatever ground, is limited to the amount (excluding VAT) the Customer paid Huispedia for the API in the 12 months before the first event causing the damage, with a maximum of € 500 per calendar year. Related events count as one event. This article prevails over article 12.2 of the General Terms.

**14.4** A right to compensation only arises if the Customer reports the damage in writing within 30 days of discovering it. Claims lapse 12 months after the event causing the damage.

**14.5** The Customer indemnifies Huispedia against claims of third parties, including Data Sources, End Customers and data subjects under the GDPR, arising from (a) use in breach of these terms or the law, (b) use of Output in the Customer's services, or (c) calls made with the Customer's API keys. This includes fines and compensation a Data Source imposes on Huispedia and reasonable legal costs.

**14.6** If the Customer is a Consumer, paragraphs 1 to 4 do not apply and paragraph 5 applies only to use in breach of these terms or the law. Huispedia's liability towards a Consumer is governed by article 12 of the General Terms. A Consumer's statutory rights remain unaffected.

**14.7** The limitations in this article do not apply in case of intent or deliberate recklessness of Huispedia's management.

## 15. Privacy and logs

**15.1** Huispedia processes account data and request logs (such as key, IP address, endpoint, requested address and time) as controller for security, billing, fair use and reporting to Data Sources. Huispedia keeps request logs for 12 months, logs of Contract endpoints until 2 years after the end of the calendar year, and billing data for 7 years because of the statutory tax retention period. After that, Huispedia deletes or anonymises this data.

**15.2** Output may contain personal data, such as an address with a purchase price. For its own use of it, the Customer is an independent controller and complies with the GDPR.

**15.3** If Huispedia processes personal data on the Customer's behalf, the parties sign a data processing agreement on request.

## 16. Intellectual property

**16.1** All rights in the API, the models and the Output, including database rights, remain with Huispedia and its Data Sources.

**16.2** Huispedia may use the Customer's feedback freely.

## 17. Termination

**17.1** When the agreement or the account ends, the right of use ends. The Customer stops using the API immediately and deletes all stored Output within 30 days, unless Annex A prescribes a shorter period. It deletes the Output from backups as soon as they are overwritten in the normal cycle. Output in reports delivered to End Customers before termination, or that the Customer must keep by law, may remain, but is not used further. On request, the Customer confirms the deletion in writing.

**17.2** Articles 6, 12, 14, 15, 16 and 19 and Annex A (in particular A4, A7, A8 and A10) survive termination.

## 18. Changes to these terms

**18.1** Huispedia announces changes at least 30 days in advance by email and in the dashboard.

**18.2** Changes that are required by law, that a Data Source demands, or that do not materially disadvantage the Customer take effect without the Customer being able to cancel because of them.

**18.3** If a change materially disadvantages the Customer, it may cancel the agreement as of the effective date. Cancelling gives no right to a refund of credits, unless the law requires one.

**18.4** Use after the effective date counts as acceptance.

## 19. Law and disputes

Dutch law applies. Disputes go to the competent court as set out in article 19 of the General Terms: for Business Customers the court in Amsterdam (article 19.2), for Consumers under article 19.1.

## Annex A: Contract endpoints

**A1. Access.** Contract endpoints are only available after a signed agreement. Access is limited to Business Customers that Huispedia has verified through the KvK and, where applicable, the relevant professional register, and that fall into a category the Data Source concerned has allowed in writing. For Kadaster transaction data, these are currently estate agents, appraisers and mortgage advisers. The agreement states the specific purpose of use.

**A2. Purpose limitation.** The Customer requests Contract endpoints only to value one specific property in an ongoing assignment. Per valuation, the Customer receives at most 5 reference transactions plus the last known purchase price of the property itself. The Customer does not use this data for other properties or purposes.

**A3. Restricted display.** The Customer shows Transaction data only in an environment behind a login, or in a report for the client of that valuation. Not on public websites, in property listings, in marketing or in public portals.

**A4. Storage.** The Customer keeps Transaction data only in the file or report of the valuation concerned, and no longer than a statutory or professional retention duty requires. The Customer does not build its own file of transactions and does not use them to train models.

**A5. Personal data.** Transaction data may be personal data. The Customer does not use it for direct marketing (including direct mail and telemarketing) or profiling, and does not provide it to third parties other than the client of the valuation.

**A6. Source credit.** The API returns the source of each transaction. Wherever Transaction data is visible, the Customer shows that source, for Kadaster data as "Bron: Kadaster" with the year of the data. The Customer does not use the Kadaster's name and logo in any other way and does not give the impression of acting on the Kadaster's behalf.

**A7. Logging and audit.** Huispedia records every transaction supplied per Customer. The Customer cooperates with audits by Huispedia, the Kadaster or a chartered accountant and gives insight into its use within 10 working days on request.

**A8. Destruction.** When the agreement ends, or when supply by a Data Source ends, the Customer destroys all Transaction data within 5 working days and confirms this in writing. Exception: completed reports under a statutory retention duty, which the Customer does not use further.

**A9. Change by a Data Source.** If a Data Source limits, suspends or ends its supply, Huispedia may change or stop the Contract endpoints immediately. The Customer then stops using them immediately. Huispedia refunds prepaid contract fees for the remaining period pro rata.

**A10. Penalty and indemnity.** For each breach of A2 to A8, the Customer owes an immediately payable penalty of the amount stated in the signed agreement, in addition to compensation of all damage. The Customer fully indemnifies Huispedia against claims and compensation of the Kadaster and other Data Sources resulting from its breach.

**A11. Takeover.** The Customer reports a merger, takeover or demerger in advance. The right of use does not pass automatically to new group companies.

**A12. Publicity.** The Customer does not publish about the Transaction data or its origin without consulting Huispedia first.

## Annex B: Fair use policy

In one sentence: use the API as much as you like for your own processes and your own customers, as long as you do not resell the data, do not systematically collect the housing stock and do not overload the platform.

| Plan | Requests per second | Daily signal value | Contract endpoints |
| --- | --- | --- | --- |
| Free | 1 | 500 calls | No |
| Standard (Starter, Growth, Scale, Pro) | 6 | 20,000 calls, sustained | No |
| Contract / Enterprise | Per agreement | Per agreement | Yes, within Annex A |

**Permitted**

- Intensive business use by one organisation, with several users and departments within the same legal entity.
- Integration into your own software, CRM and customer portals (behind a login).
- Batch processing for your own ongoing files, with caching up to 30 days.

**Not permitted**

- Reselling raw data or making it available to third parties outside your own organisation.
- Using the API as a proxy or mirror for another data service.
- Automatically passing on calls for non-customers, such as a public portal without a white-label agreement.
- Collecting large parts of the housing stock, for example a whole municipality or the whole country in a short time.
- Using several accounts or keys to get around limits.

**Enforcement**

1. Huispedia monitors usage patterns, such as sustained peaks above the signal value and requests that systematically cover an area.
2. If misuse is suspected, Huispedia first gets in touch and looks for a solution together, such as an Enterprise or white-label contract.
3. In case of an acute risk to the platform, Huispedia may throttle immediately (HTTP 429).
4. In case of deliberate or repeated misuse after a warning, Huispedia may suspend or end access.

Huispedia may change this policy with 30 days' notice by email.