Getting Started

Getting started

Learn the essential integration patterns: authentication, schema discovery, asynchronous writes, callbacks, and sandbox testing.

This guide covers the essentials to understand before making your first API request.

Version 2 is the current API release. You can find the legacy Version 1 documentation in the version selector or at Version 1.

Feedback is welcome. Email remi@onderwijsin.nl with questions or suggestions.

The API is part of a shared digital infrastructure, developed by and for education regions (onderwijsregio’s). It supports prospective teachers and education professionals from orientation through their start in education.

The underlying Airtable system acts as an applicant tracking system (ATS) and CRM for regional coordination, data sharing, and reporting. The API provides a secure, predictable integration layer for external systems.

This documentation is intended for developers building or maintaining integrations with the platform.

Access and authentication

Access to the API is granted via an API key.

API keys are issued only to participating education regions.
Each region can create and manage multiple API keys.
Send every key in the x-api-key request header.

Authenticate requests

Request an initial key and send it securely with each API request.

Discover your schema

Before creating or updating a candidate, you should retrieve the schema for your region using the /schema endpoint. This endpoint returns the authoritative, region-specific definition of all fields that are accepted in the candidate payload. If a payload validates against the schema, it will validate against the API.

Read the schema guide

Review the shared data model and the custom fields for your region.

Asynchronous by design

All write operations (create, update, delete) are handled asynchronously by the Mutation Engine.

Successful write requests return 202 Accepted.
A 202 response means the mutation was validated and queued.
Execution happens later; it is not immediate.

Integrations must be designed with asynchronous behavior in mind.

Understand the Mutation Engine

Learn how queued mutations progress and how to handle their responses.

Idempotency and callbacks

Mutation endpoints support:

idempotencyKey for safe retries.
callbackUrl for completion and failure notifications.

These features are strongly recommended for reliable integrations.

Verify callback signatures

Confirm that callback requests were sent by the Mutation Engine.

Sandbox mode

Most endpoints support sandbox mode using the x-api-sandbox: true header.

Requests are fully validated and processed.
Production data is never modified.

Use sandbox mode during development and testing.

Sandbox environment

Use the isolated sandbox environment to validate candidate API integrations without changing production data.