Welcome! This guide helps you migrate from our legacy SOAP APIs to the new REST-based API Hub. Our REST APIs are designed to provide a modern, scalable, and developer-friendly experience — with improved performance, security, and documentation.

This guide covers:

• Dutch Business → Organization Profile API
• Monitoring API
• Address → NL Location API

🚀 Why migrate?

• Simpler integration using standard HTTP methods (GET, POST, etc.)
• Better performance and scalability
• Improved security (API key authentication)
• Interactive documentation and testing via our Documentation Hub
• Future-proof platform — all new features will be released on REST only

⚠️

SOAP is in maintenance mode. No new features will be added to the SOAP APIs. We recommend migrating as soon as possible.

🔄 Key differences: SOAP vs REST

🧭 Migration approach

1. Identify your current SOAP usage

• Which SOAP operations are you calling?
• What data fields are you consuming?
• What is your call volume?

2. Review the field mapping for your API

For each API below we provide a detailed field mapping file. This maps every SOAP field to its REST equivalent, including renamed fields, structural changes, and fields that require a different approach.

3. Request an API key

1. Request an API key via our web form
2. Add the key to your requests via the Authorization header
3. Use our interactive documentation to explore and test endpoints

4. Test in parallel

We recommend running SOAP and REST side by side during migration to validate results before switching over completely.

🇳🇱 Dutch Business → Organization Profile API

What changed

The SOAP DutchBusiness service returned organization and branch data together in a single flat response. The REST API separates these into two distinct resources:

• Organization — the legal entity (KvK registration, legal form, capital, lifecycle, insolvency)
• Branch — the physical establishment (address, personnel, SBI codes, trade names)

The main branch is embedded in the Organization response for convenience, but full branch detail is available via the Branch API.

Key things to be aware of

Organization and branch data are now separated See the field mapping file for exact paths.

Additional data blocks must be explicitly requested The REST API does not return all data by default. Financial data, management information, ownership structure, and enriched activity codes must be opted into via the ?extensions= query parameter. Available extensions: sizeIndicators, activities, financials, ownershipStructures, management, contactPerson.

Identifier fields use a system/value pattern Where SOAP returned a flat identifier (e.g. rsin_number), REST wraps it in a structure that includes the issuing authority. This pattern appears throughout the API for trade register numbers, BAG, LEI, VAT, and insolvency publication IDs.

Date format has changed SOAP returned dates as structs with separate year/month/day fields. REST returns standard ISO-8601 date strings (e.g. 2010-03-15).

Legal form codes have changed format Previously numeric (e.g. 1), now English hyphenated strings (e.g., sole-proprietorship).

Field mapping reference

The field mapping file covers all fields in the SOAP response, including exact REST paths, migration notes, and a functional description for each field.

📡 Monitoring API

What it is

The Monitoring API is a modern alternative to the SOAP update service (dutchBusinessUpdateAddDossier, dutchBusinessUpdateGetDossiers, dutchBusinessUpdateGetChangedDossiers).

ℹ️

The Monitoring API is poll-based, just like the SOAP update service. Webhook support is not yet available. If push-based notifications are important for your use case, please let us know so we can track demand.

How it works

The Monitoring API is built around two concepts: Lists and Items.

A List is a named portfolio of organizations or branches you want to monitor. You can have multiple lists — for example, one per customer segment or product.

An Item is a single organization or branch registered on a list, with configuration for which event types and data collections you want to be notified about.

When something changes in an organization or branch that matches your configuration, an Update event is generated. You can retrieve these events per list or per item, and filter them by date range, entity, or collection.

Key improvements over the SOAP update service

More granular change information The SOAP service returned only the dossier number of changed organizations — you then had to re-fetch the full dossier to find out what actually changed. The Monitoring API returns change events at the collection level, so you know exactly which part of the profile changed (e.g.,main-branch--address, insolvency-status, extension--management) before deciding whether to fetch the updated data.

Subscribe per collection When adding an item to a list, you specify which collections you care about. For example, you can monitor only insolvency-status and legal-form for a set of organizations without receiving noise about unrelated changes like address updates.

Organizations and branches The SOAP update service is tracked only at the dossier level. The Monitoring API supports monitoring both organizations and branches as separate entity types.

Cleaner polling model Like the SOAP update service, the Monitoring API is poll-based — you periodically call the updates endpoint to retrieve changes since your last check. The difference is that named lists are independent of credentials and easier to manage programmatically, and the date range filter gives you precise control over the polling window.

Available collections

You can subscribe to the following collections per entity type:

Organization collections (selection of most relevant):

Branch collections:

API at a glance

Typical workflow

1. Create a list for your use case
2. Add the organizations or branches you want to monitor, specifying which collections and event types you care about
3. Periodically poll GET .../lists/{list_id}/updates with a date range filter to retrieve new change events
4. For each relevant event, fetch the updated organization or branch profile via the Organization Profile API

ℹ️

You can filter update events by date.from and date.to, by entity.id, or by collections to narrow down results before processing.

🗺️ Address → NL Location API

What changed

The SOAP Address service exposed Dutch address data through several operations returning house number range (PCReeks) or parcel-level (Perceel) results. The REST API replaces these with a single flexible endpoint: GET /nl/locations.

Key things to be aware of

Two SOAP operations map to one REST endpoint Both addressReeksPostcodeSearch and addressReeksAddressSearch are handled by GET /nl/locations using filter parameters.

Postcode and house number are now separate parameters SOAP accepted a single concatenated string (e.g. 1234AA12). REST uses filter[postalCode] and filter[houseNumber] as separate parameters.

House letter is now a separate filter Previously bundled with houseNoAddition, the house letter is now its own dedicated filter parameter: filter[houseLetter].

The response is at individual address level SOAP returned house number ranges. REST returns individual address records. Range-level fields (huisnr_van, huisnr_tm, reeksindicatie) no longer exist.

Legacy postal format fields are not available PTT, NEN, and TPG postal formatting fields (straatnaam_ptt, plaatsnaam_nen, straatnaam_extract etc.) are not in the REST API. Use the standard street and city fields.

New capabilities available in REST The REST API adds free-text search (query), fuzzy matching (match[]), sorting, pagination control, geolocation coordinates, and BAG identifiers — none of which were available in the SOAP API.

Field mapping reference

The field mapping file covers all input parameters and response fields, including deprecated SOAP fields and new REST-only fields.

Need help?

• 📖 Explore the full API reference in our Documentation Hub
• 📧 Contact our support team
• 🐛 Found a gap or an issue? Let us know so we can prioritize it on our roadmap