Ons API migration guide 2025

On 2025-11-19, a new set of endpoints has been released which will, in time, will replace all existing endpoints. In short:

• Every existing endpoint has got a replacement endpoint with a different path, and possibly some changes in parameters.
• The old endpoints are deprecated in favour of the new endpoints.
• Both sets of endpoints will be supported until 2026-05-19.
• On 2026-05-19, the old endpoints will be removed.

Continue below for a more in-depth migration guide.

Why are the endpoints being migrated?

This Ons API migration is the result of a large migration of our internal infrastructure. Part of this internal migration was the renaming of the paths of every endpoint, in a way that it’s very clear to which Ons Suite application each endpoint belongs. Every application in the Ons Suite has since been migrated to the new endpoints, with only Ons API remaining.

What are the differences between the old and new endpoints?

The only differences between the two sets of endpoints are:

• Every endpoint has a different path:
  • The /t/ prefix has been replaced with /v0
  • For every endpoint, this prefix is followed by the name of the Ons Suite application (e.g. dossier, administration)
• For 41 endpoints, changes have been made on the path/query parameters:
  • 31 endpoints have query parameters that have been renamed.
  • 7 endpoints have moved query parameters to their path
  • 4 endpoints have moved path parameters to their query part

The mapping from th old endpoints to the new endpoints are shown here. Both sets of endpoints are contained in different OpenAPI specifications:

• The new endpoints can be found here
• The old endpoints can be found here

The following is guaranteed to have not been changed:

• Functionality and response of the endpoints
• Response/request schema/models
• HTTP methods
• OpenAPI operationId*
• OpenAPI parameter order*

_ *this is very relevant if your connector is using a generated client based on the OpenAPI spec_

How do I migrate my connector to the new endpoints?

Migration steps depend on how your connector uses Ons API. Firstly: no action is needed to get access to the new set of endpoints. Your connector already has access to the new endpoints, due to the fact that the both sets of endpoints share the same models.

• I use a generated client using the OpenAPI spec
  In this case, migration is mostly trivial: change the input OpenAPI specification from the old one to the new file. For most generators, the generated code can be used in exactly the same way due to the fact that the operationId’s and parameter order have stayed the same. However: do check that this is indeed the case for endpoints with parameters that have changed name and/or type (query vs path): generators might choose parameter order based on name or type, instead of the order in the OpenAPI specification

• I’m calling the Ons API endpoints ‘by hand’ in the connector source code
  In this case, migration requires some manual find-and-replace. To aid in this: the migration overview here might help a lot. This file also contains details on changes in parameters. Also, endpoint replacements are show in:
• The technical design section in the Ons API Dashboard
• The new Open API spec (each endpoint has a x-replacement-for header)
• The old Open API spec (each endpoint has a x-replaced-by header)

What do I do after I’ve migrated my connector?

After you’ve migrated to the new endpoints, you’ll have to mark the old endpoints as unused in the Ons API Dashboard. This can be done in the technical design of a connector version, or via the deprecated endpoints overview accessible through the profile page in the Ons API Dashboard As the old endpoints are deprecated, you will get monthly deprecation e-mails until each endpoint has been marked unused.

---