Releases

Introducing the Mutation Engine, a fully expanded candidate API, and a sandbox-ready foundation.

Overview

Version 2 is a major evolution of the Onderwijsregio API. While most integrations can migrate with minimal effort, this release introduces a new execution model and a significantly expanded API surface.

The most important conceptual change—though not strictly a breaking change—is the introduction of the Mutation Engine. All write operations are now asynchronous and processed via queued mutations. This improves reliability and predictability, but requires changes for integrations that previously assumed synchronous writes.

We strongly recommend reviewing the Mutation Engine documentation and Migration Guide before upgrading.

Key themes in this release:

• Asynchronous, resilient writes: Create, update, and delete operations are queued, rate-limited, and completed asynchronously.
• Expanded candidate management: Full CRUD support for candidates, interactions, and attachments.
• Standards-based schema and validation: /schema now returns JSON Schema that matches runtime validation.
• Improved developer experience: Sandbox support, consistent responses, explicit authentication rules, and clearer errors.

Read the Migration Guide for the complete list of breaking and non-breaking changes.

New features

This release introduces various new features, too many to document individually in this changelog. Explore the available endpoints in the interactive API reference. The highlights follow below.

Mutation Engine

All write operations in v2 are handled asynchronously by the Mutation Engine.

• All mutations return 202 Accepted.
• Writes are processed asynchronously.
• Results are delivered through callbackUrl or eventual consistency.
• Queuing, rate limiting, and idempotency are built in.

This replaces the synchronous write behavior of v1 and eliminates timeouts caused by Airtable latency.

Expanded candidate endpoints

Version 2 introduces a complete candidate management API:

• List candidates with cursor-based pagination.
• Retrieve candidates by ID.
• Find candidates by email or phone.
• Create candidates in bulk.
• Upsert or update candidates.
• Archive or permanently delete candidates.

Fields returned can be explicitly selected, and interactions can be optionally included.

Interactions API

Interactions are now first-class resources.

You can:

• List interactions for a candidate.
• Create interactions in bulk.
• Retrieve, update, and delete individual interactions.

Attachment handling

Attachments are now fully supported in the API:

• Upload CVs and other attachments during candidate creation.
• Add attachments to existing candidates.
• Remove attachments by attachment ID.
• Use public URLs or base64 uploads.

Attachments are processed asynchronously and safely transferred to Airtable.

Candidate email verification & session authentication

Introduced candidate-facing authentication flows:

• Request email verification for a candidate.
• Authenticate candidates through session tokens.
• Retrieve candidate records linked to an authenticated session.

This enables secure candidate-facing experiences without exposing region API keys.

Sandbox environment

You can now safely test integrations without touching production data.

Sandbox mode can be enabled by:

• Prefix endpoints with /sandbox.
• Or set the x-api-sandbox: true header.

Sandbox status is explicitly returned in response metadata.

Region and API key management

Regions are now first-class API resources.

New capabilities include:

• List, create, and update regions (admin-only).
• Retrieve authenticated region details.
• Create and revoke API keys programmatically.
• Receive an API key in full only once.

Admin-scoped API keys can override region context for testing and debugging.

Domain-based API structure

Endpoints are now clearly grouped by responsibility:

• Auth
• Regions
• Admin
• Schema
• Candidates
• Interactions
• Attachments
• Webhooks

This improves discoverability and clarifies authentication scope per endpoint.

Schema overhaul

The /schema endpoint has been completely redesigned.

• Returns a standards-compliant JSON Schema.
• Is generated directly from runtime validation logic.
• Is fully compatible with OpenAPI tooling and JSON Schema validators.
• Eliminates drift between documentation and runtime validation.

This replaces the proprietary schema format used in v1.

Fixes and improvements

Along with all new features, various fixes have been implemented for issues that were present in the v1 API.

Explicit authentication per endpoint

Authentication requirements are now defined per operation instead of implicitly at the API root. This prevents accidental exposure of public or candidate-facing endpoints.

Consistent response envelopes

All endpoints now return standardized success and error responses, making client-side handling predictable and uniform.

Field naming consistency

Candidate and interaction field names have been standardized and translated to English across all endpoints. Input and output field names now always match the schema.

Breaking and notable changes

• Hard API versioning: /api/v2 is a strict version boundary. Version 1 integrations must explicitly migrate.
• Asynchronous write model: All writes are asynchronous. Integrations that expect immediate results must update their flow.
• Authentication header change: Use x-api-key instead of the deprecated api-key header.
• Schema format change: Clients that parse the old /schema format must parse JSON Schema instead.

Next steps

• Review the Migration Guide for a step-by-step upgrade path.
• Read the Mutation Engine documentation to understand asynchronous behavior.
• Explore the new endpoints in the interactive API reference.

Improvements to the create endpoint and a complete overhaul of the docs.

New features

• Upsert support for /create-user: The endpoint now uses the candidate’s email address to update an existing record instead of creating a duplicate.

Fixes

• Improved error responses: Error and validation responses are more consistent and provide clearer, more actionable feedback.

Maintenance

• Improved documentation: Expanded and clarified guidance on schema usage, authentication, and integration.
• Versioned base URL: The API is now available at https://onderwijsregio.onderwijsin.nl/api/v1. The previous /api base URL remains available for the foreseeable future, but will be deprecated after Version 2 is released.

First public release of the Onderwijsregio API.

New features

• First public release: A stable, production-ready API for regional websites and third-party systems that integrate with the shared ATS infrastructure.
• Candidate onboarding: Create candidates programmatically with /create-user.
• API-key authentication: Authenticate securely at education-region scope.
• Shared candidate data model: Use a standardized schema for core candidate data across regions.
• Region-specific custom fields: Extend the shared schema for local data needs.
• Interactions: Create contact moments, activities, and referrals alongside candidates.
• Schema discovery: Inspect the candidate schema for your region through /schema.

Fixes

No fixes; this is the initial release.

Maintenance

• Deployed the core API infrastructure.
• Published the initial documentation and OpenAPI specification.