External services

Open Forms can write and read information to and from external systems. This is great when you need to integrate with existing (JSON) APIs, SOAP webservices or HTTP endpoints in general.

The connection parameters to these services are configurable in the admin interface, provided you have administrator permissions (typically this would be a different role than the people creating/managing forms).

Note

If you got to this page via the manual and don’t have permissions to manage services, please contact your functional administrator.

(API) services

We group services that (mostly) talk JSON under the (API) services. While they can be used for data in formats other than JSON, they are generally simpler to use and configure compared to SOAP and/or StUF-based services.

Examples of this type of services are:

  • the ZGW API’s

  • the Objects API

  • Haal Centraal services (BRP personen bevragen, KVK, Kadaster…)

To configure such a service, you need to have:

  • the base URL where the service is hosted

  • credentials (if relevant), like an API key or client ID/secret

Configuring a service

  1. In the admin interface, navigate to Configuration > Services.

  2. Click Add a service to bring up the configuration form.

  3. Fill out the form fields:

    • Label: provide a recognizable label. This will be displayed in dropdowns to select a service.

    • Either enter the URL to the OpenAPI specification or upload a file. For most services you can use a dummy OAS since these fields have become obsolete (and will be removed in a future update).

    • Type: Select the appropriate type or if none is relevant, select ORC (Overige).

    • API root URL: the base URL where the API is hosted. All API endpoints will be added relative to this. For example: https://example.com/api/.

    • Client ID and Secret - these are only relevant when the Authorization type is set to ZGW client_id + secret.

    • Header key the header name for the API credential when the Authorization type is set to API key. Examples are: Authorization or X-API-Key - the value depends on your API provider.

    • Header value the API credential when the Authorization type is set to API key. The exact value and format depends on your API provider. Some examples are: Token <api key> or just plainly e2c98134-3dc8-4134-88fc-aec604bf8394.

    • If mutual TLS or particular server certificates are involved (typically certificate chains signed by the G1 root), you can manage these through the Client certificate and Server certificate fields. See also our support for self-signed certificates in the installation documentation.

    • The remaining form fields can be left blank.

  4. Click Save to persist the configuration.

Dummy OAS
version: 3.0.0
info:
  title: Dummy
  version: 1.0.0
paths: {}

SOAP (and StUF) services

Note

StUF services requires a SOAP service to be configured as they are a layer on top of SOAP.

Configuring a SOAP service

  1. In the admin interface, navigate to Configuration > SOAP services.

  2. Click Add a SOAP service to bring up the configuration form.

  3. Fill out the form fields:

    • Label: provide a recognizable label. This will be displayed in dropdowns to select a service.

    • URL: if you’re defining a StUF-service, this field can be left blank because the StUF endpoints are defined elsewhere. Otherwise, you must specify the URL where SOAP messages are sent to.

    • If mutual TLS or particular server certificates are involved (typically certificate chains signed by the G1 root), you can manage these through the Client certificate and Server certificate fields. See also our support for self-signed certificates in the installation documentation.

    • The remaining form fields are optional and configuration depends on the particular service you’re connecting with.

  4. Click Save to persist the configuration.