HAAL✻CENTRAAL BRP API
BRP API / Trying the Gebeurtenissen (Events) API

Trying the Gebeurtenissen (Events) API

With the Gebeurtenissen API you can follow particular persons for specific types of event.

Short description

An “event” means that something happens to a person, in response to which you have to start a process or carry out an action. For example, when a minor being treated by youth care moves to another municipality, the case file must be transferred to the new municipality and then closed.

Often something has also changed in the person's data when an event occurs. With the event “verhuisd.intergemeentelijk”, for example, the person's address has changed and so has the municipality of registration. You can then request this in the BRP Personen API.

In the API we call following a person for a type of event a “subscription” (abonnement).

In the API you can request, at a moment of your own choosing, whether events have occurred on your subscriptions. You may choose the frequency and the moment yourself, for example once a day or every hour.

In the API, subscriptions can be managed and events requested per service or task application. The idea behind this is that not every service, task or application has the same persons (clients) and is not interested in the same events. Youth care, for example, will only have purpose limitation to follow minor clients and their parents. Social services will only follow clients who receive benefits.

In the API we call a service or task application that sets subscriptions and requests events a “subscriber” (abonnee). A subscriber will normally subscribe persons to a fixed set of event types. We call such a set of event types a “group” (groep) in the API.

Several groups can be created for one subscriber, where different persons have to be followed for a different combination of event types because they have a different role in the process. For compulsory education, for example, think of a group “pupil subject to compulsory education” and a group “parent”. Or for social services, a group “benefit recipient” and a group “partner”. A subscriber can then subscribe a person to a group, which sets a subscription for that person to all event types in the group.

When requesting events, the subscriber supplies the last event received (processed), so as to receive only events the subscriber has not yet read. This puts the subscriber in control of when and which events are received. The subscriber is therefore also responsible for ensuring that it receives all events and processes them correctly.

How do I use the API?

The API is designed for going through the following steps:

  1. the municipality (as consumer) registers a task application as a subscriber, adds one or more groups to it, and adds per group the event types for which the subscriber has purpose limitation for that group. See “Registering a subscriber”.
  2. the subscriber takes out subscriptions on persons for a group. See “Subscribing to a person”.
  3. the subscriber requests (at a certain frequency) unread events. See “Requesting events”.
  4. if there are more unread events than can be answered in one request, the subscriber repeats the previous step until all events have been read.
  5. the subscriber processes the events and, if desired, requests the changed data of the person in the BRP API /personen or /verblijfplaatshistorie.
  6. the subscriber adds a new subscription when there is a new person (client) for whom they have to receive events.
  7. the subscriber ends the subscription for a person when the subscriber no longer needs events about that person (the person is no longer a client). See “Stopping a subscription”.

To make sure you actually receive events in the pilot environment, you can send changes. Do this after setting the subscription, but before requesting events. See “Sending a change”.

Trying the API out with Postman

We have prepared a Postman project so that you can get started quickly with the Gebeurtenissen API. The project contains a number of example messages.

To make this work in the pilot environment, you must enter the following values under Variables in Postman:

You can also use different subscribers and/or different citizen service numbers in the various requests. In that case change {{abonneeNaam}} and/or {{burgerservicenummer}} to the desired value.

Specifications

View the specifications in ReDoc. The OpenAPI specifications of the Gebeurtenissen API can be downloaded as OAS3 BRP-API Gebeurtenissen. Use them to generate consumer code.

Authentication

To be able to use the API you must send an OAuth token with every request.

To request a token in the pilot environment, send a request like this:

curl --location 'https://probeerbrpapi.rvig.nl/realms/brp-api/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id={{client-id}}' \
--data-urlencode 'client_secret={{client-secret}}' \
--data-urlencode 'scope={{scope}}' \
--data-urlencode 'resourceServer=ResourceServer02'

Here you must replace everything between double braces with the credentials you have received.

The token you must send with every request is in the reply, in “access_token”.

Registering a subscriber

Before an application can use the Gebeurtenissen API to set subscriptions and request events, you must register it as a subscriber.

To register a subscriber in the pilot environment, send a request like this:

curl --location 'https://probeerbrpapi.rvig.nl/api/brp/abonnees' \
--header 'Content-Type: application/json' \
--header 'Authorization: {{token}}' \
--data '{
  "naam": "{{naam van de abonnee}}"
}'

Before the subscriber can take out a subscription, you must add a group to the subscriber. To add a group to the subscriber, send a request like this:

curl --location 'https://probeerbrpapi.rvig.nl/api/brp/abonnees/{{naam van de abonnee}}/groepen' \
--header 'Content-Type: application/json' \
--header 'Authorization: {{token}}' \
--data '{
  "naam": "{{naam van de groep}}"
}'

Then add the event types to the group that the subscriber wants and is permitted to receive for this group. To add an event type to the group, send a request like this:

Subscribing to a person

To take out a subscription in the pilot environment, send a request like this:

Requesting events

To receive events in the pilot environment, send a request like this:

Stopping a subscription

To end a subscription in the pilot environment, send a request like this:

Ending a subscription is a POST request to the same URL you use for taking out a subscription. The value of “type” in the body determines what the API does here.

Sending a change

In the pilot environment it is possible to send changes, so that you can determine yourself which events you get in your tests.

This does two things:

There are currently three kinds of change:

With the change you also supply the new data.

Event verhuisd.intergemeentelijk (moved between municipalities)

Event verhuisd.naar-buitenland (moved abroad)

Event overleden (died)

Consulting

It is possible to consult everything you create. For this, use the “GET” operations with method “GET” (see the API specifications).

For example, to consult the event types in a group in the pilot environment, send a request like this:

To consult all active subscriptions in the pilot environment, send a request of the same kind.

Deleting the subscriber and its groups and subscriptions

It is possible to delete everything you create. For this, use the “DELETE” operations (see the API specifications).

When you delete something, all underlying items are deleted immediately as well:

To delete a subscriber and all underlying groups and subscriptions in the pilot environment, send a request of the same kind.

The source page contains a further eight curl examples for these operations. They are reproduced in the source; only the surrounding instructions are translated here.