The sandbox environment is available for all non-production use cases. It provides access to the same API features as production, while being fully isolated from production data. This allows you to develop and test safely without polluting your region’s live data.

Supported routes

The sandbox environment currently supports all routes under /api/v2/candidates. If the x-api-sandbox header is set for other routes, it will be ignored.

You can confirm the sandbox feature is enabled in the meta property of the API reponse:

{
	"statusCode": 200,
	"message": "Successfully retrieved ...",
	"data": { ... },
	"meta": {
		"sandboxEnabled": true
	}
}

Enabling the Sandbox

You can enable the sandbox in one of two ways:

Option 1: Use the /sandbox endpoint prefix

Replace /v2 with /sandbox in the API endpoint.

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

Option 2: Set a request header

Include the following header in your request:

x-api-sandbox: true

Data Scope and Persistence

Sandbox data is scoped to your region. This means that any API key belonging to the same region has access to the same sandbox data.

To prevent an excessive buildup of test data, the sandbox is cleared automatically once per day. As a result, any test data you create should be considered temporary and may be gone the next day.

Parity with Production

(Almost) all rules, conventions, and constraints that apply to the production environment—such as rate limits—also apply to the sandbox.

The primary goal of the sandbox is to offer an environment that behaves as closely as possible to production, while keeping your region’s production data clean and unaffected.

Verifying Sandbox Requests

You can confirm that a request was executed against the sandbox environment in two ways:

1. API response metadata

   The API response includes a sandboxEnabled flag in the meta property.

2. Callback request header

   When the Mutation Engine sends a callback to your provided callbackUrl, it includes the following HTTP header: x-mutationengine-sandbox-enabled. A value of true indicates the mutation was processed in the sandbox environment.