👀 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
  All create, update, and delete operations are queued, rate-limited, and finalized asynchronously.

• Massive expansion of candidate management capabilities
  Full CRUD support for candidates, interactions, and attachments.

• Standards-based schema and validation
  The /schema endpoint now returns a real JSON Schema, guaranteed to match runtime validation.

• Improved developer experience
  Sandbox support, consistent responses, explicit authentication rules, and better error visibility.

---

✨ New features

This release introduces various new features, too many to individually document in this changelog. We recommend exploring all available endpoints in the Interactive API Reference. We’ll highlight the most important new features 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 via callbackUrl or eventual consistency

• Built-in queuing, rate limiting, and idempotency

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 (bulk supported)

• Upsert candidates

• 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 (bulk supported)

• Retrieve individual interactions

• Update interactions

• Delete 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

• Support for both public URLs and 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 via 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:

• Prefixing endpoints with /sandbox

• Or setting 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

• Programmatically create and revoke API keys

• API keys are returned in full only once by design

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

• Generated directly from runtime validation logic

• Fully compatible with OpenAPI tooling and JSON Schema validators

• Eliminates drift between documentation and actual validation

This replaces the proprietary schema format used in v1.

---

🛠️ Fixes & 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 & notable changes

• Hard API versioning
  Introduced /api/v2 as a strict version boundary. v1 integrations must explicitly migrate.

• Asynchronous write model
  All write operations are now async. Integrations relying on immediate write results must update their flow.

• Authentication header change
  Use x-api-key instead of the deprecated api-key header.

• Schema format change
  Clients parsing the old /schema format must update to JSON Schema parsing.

---

📘 Next steps

• Review the Migration Guide for a step-by-step upgrade path

• Read the Mutation Engine documentation to understand async behavior

• Explore the new endpoints using the Interactive API Reference