Upgrade guide

A step-by-step checklist for migrating from Version 1 to Version 2.

Even though this is a major release, most migrations are straightforward. If your integration only submits new candidates, upgrading typically takes less than 10 minutes.

Who this guide is for

This guide is intended for developers migrating an existing v1 integration to v2.

Migration effort depends on your use case:

• Easy (~10 minutes): You only create candidates and do not rely on Version 1 schema parsing.
• Moderate (~30–60 minutes): You update candidates, submit interactions, or dynamically map fields.
• Advanced (1–2+ hours): You generate forms or validation logic from the Version 1 /schema response, or assume synchronous writes.

Overview

Version 2 introduces many new features with only a small number of breaking changes. Most breaking changes are the result of stricter naming conventions and can be resolved by updating property names.

The most important conceptual change—though not strictly breaking—is the introduction of the Mutation Engine. All write operations are now asynchronous. Integrating this properly may require small changes to your application flow.

We strongly recommend reviewing the Mutation Engine documentation before starting your migration.

Read the Mutation Engine guide before starting your migration.

Handle asynchronous writes

All create, update, and delete operations in v2:

• Return 202 Accepted.
• Are processed asynchronously.
• Complete through callbacks or eventual consistency.

If your v1 integration assumed immediate write results, you must update your logic.

Mandatory steps

Complete all steps in this section to avoid breaking changes in your application.

Change the base URL

The new API is accessible at:

https://onderwijsregio.onderwijsin.nl/api/v2

All endpoints referenced in the documentation are relative to this base URL.

Change the authentication header

The old api-key header is deprecated. Use the x-api-key header instead.

Map candidate field keys

The field names in the candidate schema have been translated from Dutch to English, along with several additional standardization changes.

From version 1.1 onward, the /create-user endpoint returned the newly created record exactly as defined in Airtable, using Airtable’s record field keys. These keys differed from the field keys returned by the /schema endpoint.

In version 2, all field keys have been fully standardized for both input and output. This ensures consistency across endpoints.

Refer to the table below for the new field key mappings.

As in version 1, you should introspect the (custom) fields schema via the /schema endpoint to retrieve the available custom field mappings.

Map interaction field keys

Similar to the candidate schema, the field keys for interactions have also been renamed and standardized in version 2.

Refer to the table below for the updated interaction field mappings.

Use the new custom-fields interface

Custom fields are now modeled as a nested JSON Schema object under customFields.

They:

• Use the same JSON Schema constructs as shared fields
• Are region-specific and dynamically generated
• Must always be discovered via /schema
• Are validated only when known (see custom field validation behavior)

This replaces the legacy objectArray-based custom field modeling from v1.

Complete the checklist

• Change the base URL.
• Change the authentication header.
• Map candidate field keys.
• Map interaction field keys.
• Change the custom-fields interface.

Optional steps

These steps are optional but recommended to take advantage of new features and improvements.

Update schema handling

In version 2, the /schema endpoint has been fundamentally redesigned.

While the goal of the endpoint remains the same—describing which candidate payloads are accepted—the schema is no longer a custom, proprietary format. Instead, it now returns a fully standards-compliant JSON Schema that directly mirrors API validation.

This is one of the most important improvements in v2.

This section highlights the most important differences and what you need to adapt when migrating from v1 to v2.

Compare the schema formats

In v1, the /schema endpoint returned a custom field-description format that required client-side interpretation.

In v2, the /schema endpoint returns:

• A standards-compliant JSON Schema document
• Fully compatible with OpenAPI
• Generated directly from the API’s Zod validation schemas
• Guaranteed to stay in sync with runtime validation

There is no longer any difference between:

• What the schema describes
• What the API accepts
• What the API validates

Clients that rely on the /schema response for validation, form generation, or dynamic payload construction must update their schema parsing logic when upgrading to v2.

Understand the old schema

In version 1, the schema:

• Used a custom structure (fieldName, fieldType, options, etc.)
• Required clients to interpret field semantics manually
• Modeled nested data using ad-hoc conventions (objectArray)
• Was not directly usable with JSON Schema or OpenAPI tooling
• Could drift from actual API validation logic

Example characteristics:

• Types expressed as loose strings
• Required fields inferred rather than enforced
• No formal validation rules (patterns, formats, unions)
• Limited tooling support

Use the new schema

In version 2, the /schema endpoint returns a complete JSON Schema document.

Key properties:

• Uses standard JSON Schema keywords:
  • type
  • properties
  • required
  • enum
  • format
  • oneOf / anyOf
  • additionalProperties
• Explicitly defines:
  • Required vs optional fields
  • Allowed values
  • Nested object and array structures
• Fully compatible with:
  • OpenAPI tooling
  • JSON Schema validators
  • Form generators
  • AI structured-output systems

The schema uses Zod’s native JSON Schema support. You can create your own validation logic with z.fromJSONSchema().

This ensures the schema is authoritative and cannot drift from API validation.

Integrate the sandbox environment

For non-production environments, you can now use the sandbox environment. The sandbox provides access to the same API features as production but is fully isolated from production data. You can use the same API keys as usual.

To enable the sandbox, use one of the following approaches:

• Prefix the endpoint with /sandbox instead of /v2. Example:

  https://onderwijsregio.onderwijsin.nl/api/sandbox/schema
  

• Set the x-api-sandbox header to true

Explore the new endpoints in the API Explorer

Version 2 introduces dozens of endpoints. Explore, inspect, and test them in the interactive API reference.