> For the complete documentation index, see [llms.txt](https://docs.altum.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.altum.ai/ontwikkelaars/overstappen-naar-altum-ai.md).

# Overstappen naar Altum AI

Deze gids helpt developers die al een andere woningdata-API gebruiken om over te stappen naar Altum AI. Met de eerste werkende call en een eerste veldmapping begin je in een middag.

## Wat je nodig hebt

* Een account op het [Altum AI Platform](https://platform.altum.ai/)
* Een API-sleutel (header `x-api-key`)
* Ongeveer een middag voor de eerste werkende call en een eerste veldmapping
* Optioneel: [Postman](https://www.postman.com/downloads/) voor snelle tests

## Stappenplan

1. [Account en API-sleutel](#1-account-en-api-sleutel)
2. [Sandbox (zonder credits)](#2-sandbox)
3. [Eerste API-call](#3-eerste-call)
4. [Postman API Collection](#4-postman-api-collection)
5. [Velden en endpoints vergelijken en mappen](#5-velden-en-endpoints-vergelijken-en-mappen)
6. [Prijzen en credits](#6-prijzen-en-credits)
7. [Overschakelen naar productie](#7-overschakelen-naar-productie)

***

## 1. Account en API-sleutel

Maak een account via de [inschrijfpagina](https://platform.altum.ai/auth?register=1).

Je API-sleutel:

* Genereer je op het Platform, of krijg je bij een abonnement. Zie [API-sleutel](https://docs.altum.ai/ontwikkelaars/api-sleutel.md).
* Stuur je mee in de header `x-api-key` op `https://api.altum.ai`.
* Zonder geldige sleutel wordt het verzoek niet geauthenticeerd.

Voorbeeldheader:

```plaintext
x-api-key: JOUW_UNIEKE_API_SLEUTEL
```

Meer context over credits en abonnementen: [Platform](https://docs.altum.ai/platform) en [Credits en prijzen](https://docs.altum.ai/platform/credits-en-prijzen).

***

## 2. Sandbox

Gebruik eerst de [sandbox](https://docs.altum.ai/ontwikkelaars/sandbox). Zo test je integraties zonder credits te verbruiken.

* Sandbox-calls verbruiken geen credits en wijzigen je creditsaldo niet.
* Voeg `/sandbox/` toe aan het URL-pad van het endpoint.
* Gebruik de sandbox-API-sleutel die op de Sandbox-pagina staat (publiek gedocumenteerd).
* Voorbeeld: `POST https://api.altum.ai/sandbox/avm`

Welke API's sandbox ondersteunen, staat in de checklist op de [Sandbox-pagina](https://docs.altum.ai/ontwikkelaars/sandbox).

curl-voorbeeld (zie [Voer de eerste API-call uit](https://docs.altum.ai/ontwikkelaars/setting-up-an-api-call)):

```bash
#!/bin/bash

curl -X POST https://api.altum.ai/sandbox/avm -H "x-api-key: m2ipzWVV3e9yPU9TduqpY4oZTbcEHCGj31GLVLYB" -H "Content-Type: application/json" --data-binary @- <<DATA
{
   "postcode" : "1234AB",
   "housenumber" : "1"
}
DATA
```

Vervang later de sandbox-sleutel door je eigen productiesleutel en verwijder `/sandbox/` uit het pad wanneer je overschakelt.

***

## 3. Eerste call

Volg [Voer de eerste API-call uit](https://docs.altum.ai/ontwikkelaars/setting-up-an-api-call).

Daar zie je hoe je een call doet in Reqbin, Insomnia en Postman, inclusief:

* Endpoint-URL op `api.altum.ai`
* Header `Content-Type: application/json`
* Header `x-api-key`
* Body als raw JSON bij POST

Minimale requeststructuur (zie [Postman API Collection](https://docs.altum.ai/ontwikkelaars/postman-api-collection)):

```json
{
  "postcode": "2728KH",
  "housenumber": 7,
  "valuationdate": "20260126"
}
```

Kies daarna de API die bij jouw use case past (bijvoorbeeld Woningwaarde, WOZ, Woningkenmerken) via de zijbalk of de startpagina [Altum AI API documentatie](https://docs.altum.ai/).

Wil je de volledige technische specificatie? Zie [OpenAPI specificaties](https://docs.altum.ai/ontwikkelaars/openapi-specificaties).

***

## 4. Postman API Collection

Met de [Postman API Collection](https://docs.altum.ai/ontwikkelaars/postman-api-collection) test je endpoints snel. Per request zie je welke invoer en output verwacht worden.

Stappen:

1. Download de collectie vanaf de Postman-pagina in de docs.
2. Importeer het bestand `Altum APIs.postman_collection.json` in Postman.
3. Zet op het tabblad Variables van de collectie je `API_KEY` (sandbox of productie).
4. Base URL: `https://api.altum.ai`
5. Header key: `x-api-key`

Handig bij overstappen: per endpoint vergelijk je input en output met je huidige integratie, zonder meteen code te wijzigen.

***

## 5. Velden en endpoints vergelijken en mappen

Doel: jouw bestaande calls één voor één laten werken op Altum AI.

### 5.1 Inventaris van je huidige calls

Maak een korte lijst:

| Jouw huidige call | Doel (bijv. waarde, WOZ, kenmerken) | Inputvelden | Outputvelden die je app gebruikt |
| ----------------- | ----------------------------------- | ----------- | -------------------------------- |
| ...               | ...                                 | ...         | ...                              |

### 5.2 Per call de passende Altum-API zoeken

1. Zoek in de docs-zijbalk of via [llms.txt](https://docs.altum.ai/llms.txt) de API die hetzelfde doel dekt.
2. Open de pagina Authenticatie, invoer en resultaat van die API.
3. Noteer het productie-endpoint (bijvoorbeeld `POST https://api.altum.ai/avm` voor de Woningwaarde API) en het sandbox-pad (`/sandbox/...`).

Voorbeelden van startpunten:

* Woningwaarde: [Authenticatie, invoer en resultaat](https://docs.altum.ai/taxeren-en-waarderen/woningwaarde-api/authentication-input-and-response)
* WOZ: [Authenticatie, invoer en resultaat](https://docs.altum.ai/woningdata/woz-api/authentication-input-and-response)
* Woningkenmerken: [Authenticatie, invoer en resultaat](https://docs.altum.ai/woningdata/woningkenmerken-api/authenticatie-invoer-en-resultaat)

### 5.3 Inputvelden mappen

Veel Altum-API's gebruiken adresvelden zoals:

| Altum-veld (typisch) | Betekenis                                   |
| -------------------- | ------------------------------------------- |
| `postcode`           | Nederlandse postcode, bijvoorbeeld `1234AB` |
| `housenumber`        | Huisnummer                                  |
| `houseaddition`      | Huisletter en/of toevoeging als één string  |
| `valuationdate`      | Waarderingsdatum, vaak `YYYYMMDD`           |

Details over huisnummers en toevoegingen: [Huisnummers & toevoegingen](https://docs.altum.ai/taxeren-en-waarderen/woningwaarde-api/house-numbers-and-additions).

Vuistregel:

* Een huisletter is altijd één letter.
* Een toevoeging kan letters of cijfers zijn en meer dan één teken.
* Combineer letter en toevoeging in `houseaddition`, bijvoorbeeld `"A02"`, `"02"`, `"A"`, `""` of `"2B"`.

Let op: veldnamen verschillen per API. Lees altijd de Authenticatie-pagina van de API die je gebruikt. Sommige oudere of andere API's gebruiken varianten zoals `post_code` / `house_number` (zie [Migratiehandleiding v1 naar v2](https://docs.altum.ai/verduurzamen/nta-8800-energielabel-v2-api/woningen/migratiehandleiding-v1-v2) voor NTA 8800). Neem veldnamen niet zomaar over uit je huidige integratie zonder mappingtabel.

Werkwijze:

1. Zet naast elk oud inputveld het Altum-veld.
2. Markeer verplichte velden (rood gemarkeerd in de docs-tabellen).
3. Converteer types (string vs number) volgens de docs.
4. Test eerst met sandbox-data.

### 5.4 Outputvelden mappen

1. Roep de sandbox aan met een bekend adres.
2. Vergelijk de responsekeys met wat jouw applicatie nu leest.
3. Maak een mappinglaag in je code (oud veld naar Altum-veld), zodat je de rest van je app niet in één keer hoeft te herschrijven.
4. Gebruik de pagina Resultaat interpretatie van de betreffende API voor betekenis van velden.

### 5.5 Testen in de sandbox

Per gemapte call:

1. Zelfde scenario als in productie, maar op `/sandbox/` met de sandbox-sleutel.
2. Controleer HTTP-status en body.
3. Los validatiefouten op via [422](https://docs.altum.ai/api-error-codes/422), authenticatie via [403](https://docs.altum.ai/api-error-codes/403), en rate limits via [429](https://docs.altum.ai/api-error-codes/429).
4. Herhaal tot input/output stabiel zijn.

***

## 6. Prijzen en credits

Op het Platform betaal je met credits. Elke API heeft een vaste creditwaarde per call, en sandbox-calls verbruiken geen credits.

Hoeveel credits een call kost, zie je in de [Kostencalculator](https://platform.altum.ai/abonnement?tab=calculator) op het Platform.

***

## 7. Overschakelen naar productie

Als de sandbox-mapping klopt:

1. Vervang de sandbox-sleutel door je productiesleutel uit het Platform.
2. Verwijder `/sandbox/` uit het pad.
3. Monitor je creditsaldo op [platform.altum.ai](https://platform.altum.ai/) (het saldo kan ongeveer één minuut achterlopen op de call; zie [Credits en prijzen](https://docs.altum.ai/platform/credits-en-prijzen)).
4. Optioneel: volg verbruik via de [Verbruik-API](https://docs.altum.ai/ontwikkelaars/verbruik-api) (die rapporteert calls, niet credits).

***

## Checklist

* [ ] Account aangemaakt en API-sleutel opgeslagen (niet in publieke repo's)
* [ ] Minstens één sandbox-call succesvol
* [ ] Postman-collectie geïmporteerd met je sleutel
* [ ] Inventaris van huidige calls gemaakt
* [ ] Per belangrijke call: Altum-API gekozen, input/output gemapt, sandbox getest
* [ ] Credits per call bekeken in de Kostencalculator
* [ ] Productiepad klaar (zonder `/sandbox/`, met productiesleutel)

## Hulp

* Docs: [docs.altum.ai](https://docs.altum.ai/)
* Support: <support@altum.ai> (zie [Platform](https://docs.altum.ai/platform))


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.altum.ai/ontwikkelaars/overstappen-naar-altum-ai.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
