.. _api_experimental: ======================================= Experimental features of Open Zaak APIs ======================================= Open Zaak implements APIs, which adhere to :ref:`VNG standards `. Moreover it provides extra features which are not included in the standards. All such features are marked as "experimental" (or "experimenteel") in the OAS. There are no breaking changes from the VNG standards and these changes are mostly small additions for the convenience of the clients. Below is the full list of deviations. Zaken API ========= Notities -------- The ``zaaknotities`` endpoint has been added to the Zaken API and supports GET, POST, PUT, PATCH and DELETE operations. * ``/api/v1/zaaknotities`` Notifications ------------- For ``zaken`` notification channel a new "kenmerk" ``zaaktype.catalogus`` is added. .. _cloud_events: Cloud events ------------ .. note:: Enabling cloud events requires some configuration, see :ref:`cloud_events_configuration` for additional information on this. Sending of cloud events is still under development and **NOT** suited for production use, but currently Open Zaak can emit the following cloud events if configured: * ``nl.overheid.zaken.zaak-gemuteerd``: this event is emitted emitted whenever a change is is made to the Zaak or related resources that could be relevant for the initiator of the Zaak: * PUT/PATCH on ``/zaken`` * POST on ``/statussen`` * POST on ``/substatussen`` * POST/PUT/PATCH/DELETE on ``/resultaten`` * POST/PUT/PATCH/DELETE on ``/zaakinformatieobjecten`` * POST/PUT/PATCH/DELETE on ``/zaakobjecten`` * POST/PUT/PATCH/DELETE on ``/resultaten`` * POST/PUT/PATCH/DELETE on ``/besluiten`` (if the Besluit is related to a Zaak) This event is also emitted via the convenience endpoints: * ``/zaken/api/v1/zaak_registreren`` * ``/zaken/api/v1/zaak_opschorten/{uuid}`` * ``/zaken/api/v1/zaak_verlengen/{uuid}`` * ``/zaken/api/v1/zaak_bijwerken/{uuid}`` * ``/zaken/api/v1/zaak_afsluiten/{uuid}`` * ``/documenten/api/v1/document_registreren`` * ``besluiten/api/v1/besluit_verwerken`` (if the Besluit is related to a Zaak) * ``nl.overheid.zaken.zaak-verwijderd``: when deleting a Zaak * ``nl.overheid.zaken.zaak-geopend``: when the Zaak information is seen by the end user (can be triggered with a PATCH on only ``Zaak.laatstGeopend``) * ``nl.overheid.zaken.zaak-geregistreerd``: emitted when the convenience endpoint 'zaak registreren' is called * ``nl.overheid.zaken.zaak-opgeschort``: emitted when the convenience endpoint 'zaak opschorten' is called * ``nl.overheid.zaken.zaak-bijgewerkt``: emitted when the convenience endpoint 'zaak bijwerken' is called * ``nl.overheid.zaken.zaak-verlengd``: emitted when the convenience endpoint 'zaak verlengen' is called * ``nl.overheid.zaken.zaak-afgesloten`` emitted when the convenience endpoint 'zaak afsluiten' is called A webhook endpoint ``/events`` has been added where incoming events can be delivered. .. warning:: In order to make sure that cloud events are only sent when the initial Zaak is "complete" (meaning that it has all the required resources to be considered a valid Zaak, such as a Rol for the `initiator`), the assumption is made that the initial Status will only be set by client applications once the initial Zaak is complete (meaning that the Rollen already exist before adding the Status). No validation exists for this currently, but in the future this will likely be enforced via validation on the API endpoints. Example of a ``nl.overheid.zaken.zaak-gemuteerd`` cloud event in its current shape: .. code-block:: json { "specversion": "1.0", "type": "nl.overheid.zaken.zaak-gemuteerd", "source": "urn:nld:oin:01823288444:zakensysteem", "subject": "89b06186-c133-4c74-8492-b43392bc4fdb", "id": "b386ff52-de66-4fde-805f-6c80b4f3cc68", "time": "2025-11-28T09:57:45Z", "dataref": "/zaken/api/v1/zaken/89b06186-c133-4c74-8492-b43392bc4fdb", "datacontenttype": "application/json", "data": { "bronorganisatie": "000000000", "zaaktype": "http://open-zaak.local/catalogi/api/v1/zaaktypen/c9d5df4e-8c2e-46b7-9d05-e5172c1290a2", "zaaktype.catalogus": "http://open-zaak.local/catalogi/api/v1/catalogussen/f4c18dd3-124d-47f0-9d8a-c0bfaa2ceba0", "vertrouwelijkheidaanduiding": "openbaar" } } The shape of these cloud events and the actions that trigger these cloud events are still subject to change. Currently these events are sent directly to a configured webhook, but in the future it will be possible to route these cloud events via Open Notificaties as well. Endpoints --------- New endpoints are added: * PUT ``/api/v1/rollen/{uuid}`` * POST ``/api/v1/zaaknummer_reserveren`` – reserve a zaaknummer (identificatie) in combination with a bronorganisatie. The optional ``amount`` attribute can be specified to reserve identifications in bulk * POST ``/api/v1/zaak_registreren`` – create a zaak in combination with a status, rollen, zaakinformatieobjecten & zaakobjecten to immediately link them to this zaak. * POST ``/api/v1/zaak_opschorten/{uuid}`` - suspend a zaak and set a new status for the zaak * POST ``/api/v1/zaak_verlengen/{uuid}`` - extend a zaak and set a new status for the zaak * POST ``/api/v1/zaak_bijwerken/{uuid}`` - update a zaak in combination with a status & rollen to immediately link them to this zaak. * POST ``/api/v1/zaak_afsluiten/{uuid}`` - close a zaak by creating a status and resultaat for the zaak. * GET ``/api/v1/substatussen`` * POST ``/api/v1/substatussen`` Attributes ---------- * ``ZaakEigenschap``: * ``waarde`` attribute is changed: an extra validation is added against ``eigenschap.specificatie`` value if ``ZAAK_EIGENSCHAP_WAARDE_VALIDATION`` env variable is turned on * Request body of ``/api/v1/zaken/_zoek``: * ``zaaktype__not_in`` search attribute is added * ``Rol``: * ``betrokkeneIdentificatie.identificatie`` max length is changed from 24 to 128 for ``betrokkeneType: "medewerker"`` * ``betrokkeneIdentificatie.nietNatuurlijkPersoonIdentificatie.kvkNummer`` is added to support :ref:`mandates ` * ``betrokkeneIdentificatie.vestigingsNummer`` is added for ``betrokkeneType: "niet_natuurlijk_persoon"`` as ``betrokkeneType: "vestiging"`` has been deprecated. * ``roltoelichting`` is changed to not required * Two attributes are added to track the validity period of a ``Rol`` within a ``Zaak``: * ``beginGeldigheid``: the date on which the validity period starts * ``eindeGeldigheid``: the date on which the validity period ends * For ``betrokkeneType: "organisatorische_eenheid"`` * ``betrokkeneIdentificatie.identificatie`` max length is changed from 24 to 255 * ``betrokkeneIdentificatie.naam`` max length is changed from 50 to 255 * ``betrokkeneIdentificatie.isGehuisvestIn`` max length is changed from 24 to 255 * ``Zaak``: * ``communicatiekanaalNaam`` is added * ``relevanteAndereZaken.aardRelatie`` is changed: a new enum value "overig" is added * ``relevanteAndereZaken.overigeRelatie`` is added * ``relevanteAndereZaken.toelichting`` is added * ``opschorting.eerdereOpschorting`` is added to indicate whether or not a Zaak has been suspended in the past * ``laatstGemuteerd`` is added to indicate when the most recent change happened to a Zaak (or a resource related to that Zaak) that could be relevant for the initiator of the Zaak. * ``laatstGeopend`` is added to indicate when the Zaak was last opened/seen by the end user (citizen) * ``betalingsindicatie`` has new enum values, the original values have been marked as deprecated * ``gefactureerd``: Invoice order sent * ``gecrediteerd``: Credit order sent * ``betaald``: Payment established (for example via online checkout with direct application) * ``nvt``: No costs involved * ``relevanteAndereZaken`` is marked as deprecated * ``gerelateerdeZaken`` is added Query parameters ---------------- * ``/api/v1/rollen`` endpoint. Added new parameters to support :ref:`mandates `: * ``betrokkeneIdentificatie__nietNatuurlijkPersoon__kvkNummer`` * ``betrokkeneIdentificatie__nietNatuurlijkPersoon__vestigingsNummer`` * ``betrokkeneIdentificatie__vestiging__kvkNummer`` **(scheduled for deprecation in Open Zaak version 3.0)** * ``machtiging`` * ``machtiging__loa`` * ``/api/v1/zaken`` endpoint. Added new parameters to support :ref:`mandates `: * ``rol__betrokkeneIdentificatie__nietNatuurlijkPersoon__kvkNummer`` * ``rol__betrokkeneIdentificatie__nietNatuurlijkPersoon__vestigingsNummer`` * ``rol__betrokkeneIdentificatie__vestiging__kvkNummer`` **(scheduled for deprecation in Open Zaak version 3.0)** * ``rol__machtiging`` * ``rol__machtiging__loa`` * ``/api/v1/zaken`` endpoint. Other new parameters: * ``kenmerk__bron`` * ``kenmerk`` A bron-kenmerk combination of a zaak. (format: ``:``) * ``status__statustype`` – filter Zaken by the current status that has the given statustype. Accepts a statustype URL. * ``resultaat__resultaattype`` – filter Zaken by the resultaat with the specified resultaattype. Accepts a resultaattype URL. Documenten API ============== Notifications ------------- For ``documenten`` notification channel a new "kenmerk" ``informatieobjecttype.catalogus`` is added. Endpoints --------- New import endpoints are added: * ``/import/create`` * ``/import/{uuid}/upload`` * ``/import/{uuid}/status`` * ``/import/{uuid}/report`` * ``/import/{uuid}/delete`` The usage of import endpoints is described :ref:`here `. New endpoints are added: * ``/api/v1/documentnummer_reserveren`` – reserve a documentnummer (identificatie) in combination with a bronorganisatie. The optional ``amount`` attribute can be specified to reserve identifications in bulk * ``/api/v1/document_registreren`` – create a enkelvoudiginformatieobject in combination with a zaakinformatieobject to immediately link it to a zaak. Query parameters ---------------- * ``/api/v1/enkelvoudiginformatieobjecten`` endpoint. Added new parameters: * ``auteur`` * ``beschrijving`` * ``creatiedatum__gte`` * ``creatiedatum__lte`` * ``informatieobjecttype`` * ``locked`` * ``objectinformatieobjecten__object`` * ``objectinformatieobjecten__objectType`` * ``ordering`` * ``titel`` * ``trefwoorden__overlap`` * ``vertrouwelijkheidaanduiding`` Catalogi API ============ Attributes ---------- * ``ResultaatType``: * ``brondatumArchiefprocedure.datumkenmerk`` is changed and supports nested path as value * ``brondatumArchiefprocedure.afleidingswijze``: ``gerelateerde_zaak`` has been marked as deprecated * ``StatusType``: * ``eigenschappen`` is made read-only. `The reason `__ * ``BesluitType``, ``Eigenschap``, ``InformatieObjectType``, ``ZaakType``, ``ResultaatType``, ``RolType``, ``StatusType``, ``ZaakObjectType``: * ``beginObject`` and ``eindeObject`` are made read-only. `The reason `__ Validation ---------- * ``ResultaatType``: * ``brondatumArchiefprocedure.afleidingswijze``: ``termijn`` is allowed for all selectielijstklasse procestermijnen except ``nihil``. This differs from the Catalogi API specification, because there ``termijn`` is only allowed for ``procestermijn`` ``ingeschatte_bestaansduur_procesobject`` (see `Catalogi API runtime behavior (ztc-003) `_) Query parameters ---------------- * ``/api/v1/informatieobjecttypen`` endpoint. Added new parameters: * ``zaaktype`` * ``omschrijving__icontains`` - filter by (a part of the) ``omschrijving`` (case-insensitive match). * ``/api/v1/roltypen`` endpoint. Added new parameters: * ``omschrijving`` - filter by (a part of the) ``omschrijving`` (case-insensitive match). * ``/api/v1/zaakobjecttypen`` endpoint. Added new parameters: * ``status`` – filter ZaakObjectType by concept status: "concept", "definitief", or "alles" * ``/api/v1/zaaktypen`` endpoint. Added new parameters: * ``omschrijving__icontains`` – filter by (a part of the) ``zaaktype_omschrijving`` (case-insensitive match). * ``identificatie__icontains`` – filter by (a part of the) ``identificatie`` (case-insensitive match). Besluiten API ============= Notifications ------------- For ``besluiten`` notification channel a new "kenmerk" ``besluittype.catalogus`` is added. Cloud events ------------ Sending of cloud events is still under development and **NOT** suited for production use, but currently Open Zaak can emit the following cloud events if configured: * ``besluit-verwerkt`` emitted when the convenience endpoint 'besluit verwerken' is called Endpoints --------- New endpoints are added: * ``/api/v1/besluit_verwerken`` – create a besluit in combination with one or more besluitinformatieobject(en) to immediately link them. Cloud events ------------ Sending of cloud events is still under development and **NOT** suited for production use, but currently Open Zaak can emit the following cloud events if configured: * ``document-geregistreerd`` emitted when the convenience endpoint 'document registreren' is called Autorisaties API ================ No deviation from the standard