API Design Rules GEMMA-compliant Comply-or-explain

Custom VNG API integration development

Appfront builds and validates integrations in line with the VNG/GEMMA API standards and the Dutch API Design Rules (ADR). For municipalities and software suppliers, we build REST APIs that demonstrably meet the standard, from Customer Interactions, Requests and Open Council Information to Haal Centraal queries on the base registries. If your focus is case-oriented working, see our page on the ZGW API integration. You integrate in line with the comply-or-explain principle and keep control over your suppliers.

What are the VNG API standards?

The VNG API standards ensure that municipal software exchanges data in a uniform, predictable way. The foundation is the NLGov REST API Design Rules (ADR): design rules for REST APIs, maintained by Logius and mandatory under the comply-or-explain principle via Forum Standaardisatie. This page covers that broader family of standards, not case-oriented working specifically. For the ZGW APIs, please see our ZGW API integration.

On top of the API Design Rules sit domain standards from the GEMMA landscape of VNG Realisatie: Customer Interactions (with Customers, Contact Moments and Requests), Open Council Information, IMWOZ queries and Rules for Activities. There are also the Haal Centraal queries, which allow municipalities to retrieve data directly from the base registries: BRP, BAG, WOZ, HR and BRK. In practice, integrating compliantly means following the right information model, adhering to the ADR and demonstrating this via the VNG API test facility.

Appfront builds in line with the official NLGov REST API Design Rules and the accompanying information model for each standard. We translate the agreements into a working, testable integration, align authorisation and error handling with your landscape, and make sure the implementation keeps pace when a standard gets a new version. Whether you are a municipality that wants to steer its suppliers or a supplier that wants to connect in a GEMMA-compliant way, the standard is our starting point.

API Design Rules (ADR)

The NLGov design rules for REST APIs: predictable resources, OpenAPI 3.x documentation, correct HTTP methods and status codes, pagination and versioning. Mandatory under comply-or-explain for government organisations.

GEMMA domain standards

Customer Interactions (Customers, Contact Moments, Requests), Open Council Information, IMWOZ queries and Rules for Activities, each with its own information model within the GEMMA reference architecture of VNG Realisatie.

Demonstrably compliant

With the VNG API test facility, you demonstrate that a completed API meets the standard. Essential for tenders and RFI processes in which municipalities want to hold suppliers to the standards.

Our process for a VNG API integration

We work with a proven methodology that removes uncertainty early and delivers a testable, standards-compliant integration. From analysing the right standard and information model to validation via the API test facility and ongoing maintenance, every step is aimed at an integration that your team can understand and keep demonstrably compliant.

1
Analysis & scope

We determine which VNG/GEMMA standard applies, which data you exchange, which authorisation requirements apply and how the standard relates to your existing systems.

2
Architecture

We design the integration against the API Design Rules and the information model, choose the right authentication (such as OAuth 2.0 NL GOV and PKIoverheid) and draw up an error-handling strategy.

3
Development

Implementation with automated tests, structured logging and monitoring. We test continuously against the standard. You see working builds along the way.

4
Go-live & maintenance

Validation via the API test facility and a controlled go-live with a safety net, followed by ongoing maintenance and further development as the standard evolves.

What a VNG API integration delivers in practice

Every integration is set up specifically for the standard you need, your information model and the neighbouring systems. Below are the capabilities we deliver most often for municipalities and suppliers who want to integrate in line with the VNG/GEMMA API standards.

ADR-compliant REST APIs

APIs that follow the NLGov REST API Design Rules: correct resource naming, OpenAPI 3.x specification, proper HTTP methods and status codes, pagination, filtering and versioning. Predictable and developer-friendly, as the standard prescribes.

Customer interactions & requests

Integrations built on the Klantinteracties standard (Customers, Contact moments and Requests), so that customer contact and applications are recorded and made available in a structured way. A request is the link between the customer, products and services, and the handling process.

Haal Centraal queries

Retrieve data directly from the base registries via the Haal Centraal APIs: BRP (persons), BAG (addresses and buildings), WOZ, HR and BRK. Querying at the source, in line with the Haal Centraal specifications that have been declared a standard.

Open Raadsinformatie

Making council and committee information available via the Open Raadsinformatie standard: publishing meetings, agenda items, decisions and documents in a public, searchable form according to the VNG Realisatie OpenAPI specification.

Validation & test facility

We test the integration against the standard and run the VNG API test facility, so you can demonstrate compliance. Essential for tenders, RFI processes and supplier agreements that require the standard.

Secure authorisation

Authentication according to the NL GOV Assurance profile for OAuth 2.0, with TLS 1.3 and, where the standard requires it, PKIoverheid certificates and mutual TLS. Scoped authorisations and least privilege, with full logging of every query.

Typical use cases in practice

Working to the VNG API standards plays out differently for each organisation. We see a number of contexts come up often, and for each of them we have a working, testable setup that pays attention to the right information model, authorisation and proof of compliance.

Municipalities managing suppliers

Municipalities that want to hold their suppliers to the API standards and safeguard integrations between core systems. We translate the requirement into a testable integration and validate it via the test facility. See also our software for municipalities and municipality website.

Software vendors

Suppliers of municipal software who want to make their product available in a GEMMA-compliant way. We build or test the API against the ADR and the domain information model, deliver OpenAPI 3.x documentation and demonstrate compliance, so you can slot smoothly into tenders and RFIs.

Partnerships

Joint arrangements, regional environmental services and regional partnerships that want to bring multiple municipalities and systems into line. One set of standards-compliant integrations avoids custom work per party and keeps the landscape manageable.

RFI & tender processes

Processes in which API standards are a hard requirement. We help you translate the requirement into testable acceptance criteria, build or assess the integration and provide the evidence from the API test facility, so compliance doesn't remain a loose end.

Technology we use

We build integrations according to the VNG API standards with REST and OpenAPI 3.x, in line with the NLGov API Design Rules, combined with the backend stack that suits you. The exact choice depends on the standard and your landscape, so that your own team can manage the implementation and keep it demonstrably compliant.

NLGov REST API Design Rules (ADR) OpenAPI Specification 3.x GEMMA Klantinteracties API Verzoeken & Contactmomenten API Open Raadsinformatie API Haal Centraal (BRP / BAG / WOZ / HR / BRK) IMWOZ queries NL GOV Assurance profile for OAuth 2.0 PKIoverheid & mutual TLS TLS 1.3 REST & JSON Node.js / Python / PHP / .NET / Java / Go VNG API test facility JSON Schema validation Logging & monitoring GitHub Actions / CI-CD

Why choose Appfront for your VNG API integration?

Appfront has extensive experience building API integrations for a wide range of organisations in the Netherlands, including the public sector. We always begin with a thorough analysis of the right standard, the information model and your existing systems — an integration must not only work technically, but also demonstrably comply with the standard.

For every integration we write clear documentation and make sure your own team, or a future supplier, can understand and manage the integration. No black box, but transparent code and clear agreements on monitoring, alerting and maintenance.

You work with a dedicated point of contact who understands both the technical and the functional side. That keeps communication lines short, prevents miscommunication and speeds up decisions when choices have to be made during the build.

Also see our related standards-based integrations: ZGW API integration (case-oriented working), Haal Centraal integration and Digikoppeling, plus our custom software and AI for municipalities.

  • Builds in line with the NLGov API Design Rules and the GEMMA information model
  • Familiar with Klantinteracties, Verzoeken, Open Raadsinformatie and Haal Centraal
  • Tests and validates using the VNG API test facility
  • Security with OAuth 2.0 NL GOV, PKIoverheid and mutual TLS
  • Structured error handling and retry mechanisms
  • Extensive logging and monitoring from day one
  • Clear documentation that your team can read and maintain
  • A single point of contact, no passing you between account managers
  • Ongoing maintenance and further development as standards evolve
  • An approach tailored to your existing government IT landscape

Security and privacy in VNG API integrations

Government integrations almost always involve personal data from the base registries or sensitive process information. That is why Appfront builds in line with the NL GOV Assurance profile for OAuth 2.0: TLS 1.3 (with TLS 1.2 as a fallback) and, where the standard requires it, PKIoverheid certificates with mutual TLS for strong client authentication based on the OIN. We set up access on a least-privilege basis with scoped authorisations.

We document the data flows, authorisations and integration points so that your record of processing activities is complete and you can demonstrably comply with the GDPR — with data minimisation and purpose limitation as our starting point. Full logging of every query makes usage traceable, and we test compliance using the VNG API test facility.

More about our approach: a Digikoppeling integration for standardised message exchange, or get in touch directly for a security review of your integration.

  • GDPR-compliant data processing, purpose limitation and data minimisation
  • TLS 1.3 in transit and encryption at rest
  • PKIoverheid certificates and mutual TLS where required
  • OAuth 2.0 NL GOV with scoped, least-privilege authorisations
  • Full logging with traceable queries
  • Monitoring and alerting for anomalies
  • Secrets management following best practices
  • Documentation for your record of processing activities

Frequently asked questions about VNG API integrations

Answers to the questions we are asked most often about integrating with the VNG API standards.

The VNG API standards are the agreements that allow municipal software to exchange data in a uniform, predictable way. The foundation is the NLGov REST API Design Rules (ADR), maintained by Logius and mandatory under the comply-or-explain principle via Forum Standaardisatie. On top of these sit domain standards from the GEMMA landscape of VNG Realisatie, such as Klantinteracties (Customers, Contact moments, Requests), Open Raadsinformatie, IMWOZ queries and the Haal Centraal queries on the base registries. Case-oriented working (the ZGW APIs) is a standard in its own right within this landscape; we have a separate page for it.

The ZGW APIs (Cases, Documents, Catalogues, Decisions) are the specific standard for case-oriented working. This page covers the broader family of VNG/GEMMA API standards and the Dutch API Design Rules — the overarching design rules plus standards such as Klantinteracties, Verzoeken, Open Raadsinformatie and Haal Centraal. If you specifically want to integrate case-oriented working, see our page on ZGW API integration; the two complement each other.

Compliant integration means your API or integration demonstrably meets the applicable standard. For REST APIs, the ADR requires, among other things, correct resource naming, OpenAPI 3.x documentation, proper HTTP methods and status codes, pagination and versioning. For the domain standards, the relevant information model applies. VNG provides an API test facility that lets you demonstrate that a delivered API meets the standard, which is useful in tenders and supplier agreements.

The core is the NLGov REST API Design Rules (ADR). Around it sit, among others, Klantinteracties (Customers, Contact moments, Requests), Open Raadsinformatie, IMWOZ queries, Rules for Activities and the Haal Centraal queries on the base registers (BRP, BAG, WOZ, HR, BRK). For case-oriented working there is the separate ZGW standard. We help you determine which standard fits your use case and how it relates to your existing systems.

The cost is determined by which standard(s) you integrate, the complexity of the data flows, the number of systems to be integrated and the amount of custom business logic. Compliance verification via the API test facility, authentication requirements (such as PKIoverheid and mTLS) and ongoing maintenance also play a part. We always provide a clear quote after a no-obligation analysis of your situation.

Yes. Government data demands strict security. We work according to the NL GOV Assurance profile for OAuth 2.0, with TLS 1.3 (TLS 1.2 as a fallback) and, where the standard requires it, PKIoverheid certificates and mutual TLS for strong client authentication. We set up access on a least-privilege basis with scoped authorisations and full logging. We document the data flows so your processing register stays complete and you can demonstrably comply with the GDPR.

Yes. Appfront regularly takes over the maintenance of existing integrations, even when another party built them. We test the API against the API Design Rules and the relevant information model, run the API test facility, document the current setup and draw up improvement proposals. From then on we can handle changes, extensions and monitoring, so you stay compliant as standards evolve.

For municipalities that want to hold suppliers to the API standards, for software suppliers that want to integrate in a GEMMA-compliant way, for partnerships and joint arrangements, and for RFI and tender processes in which API standards are a requirement. We translate the standards into a working, testable integration that your own team can understand and manage.

Ready to integrate according to the VNG API standards?

Tell us which standard you need and which systems have to be integrated, whether you are a municipality that wants to steer suppliers or a supplier that wants to connect in a GEMMA-compliant way. We are happy to advise on the information model, authorisation and compliance verification via the test facility. Schedule a no-obligation advisory call and you will quickly get a clear picture of the possibilities.

Edit content