# Onderwijsregio API ## Documentation Sets - [Onderwijsregio API](https://docs.onderwijsregio.onderwijsin.nl/llms-full.txt) ## Docs - [Getting started](https://docs.onderwijsregio.onderwijsin.nl/raw/getting-started/introduction.md): Learn the essential integration patterns: authentication, schema discovery, asynchronous writes, callbacks, and sandbox testing. - [Sandbox environment](https://docs.onderwijsregio.onderwijsin.nl/raw/getting-started/sandbox-environment.md): Use the isolated sandbox environment to validate candidate API integrations without changing production data. - [Schema](https://docs.onderwijsregio.onderwijsin.nl/raw/getting-started/schema.md): Retrieve the authoritative, region-specific JSON Schema before creating or updating candidates through the API. - [Requests](https://docs.onderwijsregio.onderwijsin.nl/raw/authentication/requests.md): Request an API key for your education region and send it securely with every Onderwijsregio API request. - [Key management](https://docs.onderwijsregio.onderwijsin.nl/raw/authentication/key-management.md): Create, rotate, revoke, and securely manage the API keys assigned to your education region. - [Candidate sessions](https://docs.onderwijsregio.onderwijsin.nl/raw/authentication/candidate-sessions.md): Learn how candidates securely access their own ATS data and when to use the optional candidate session flow. - [Mutation Engine](https://docs.onderwijsregio.onderwijsin.nl/raw/mutations/mutation-engine.md): Learn how the Mutation Engine queues, processes, retries, and reports every write operation in the Onderwijsregio API. - [Callback signatures](https://docs.onderwijsregio.onderwijsin.nl/raw/mutations/callback-signatures.md): Verify Mutation Engine callback signatures with the regional signing secret to reject altered, untrusted, and replayed requests. - [Submitting candidates](https://docs.onderwijsregio.onderwijsin.nl/raw/candidates/submitting-candidates.md): Create or upsert candidates, including interactions and attachments, through the asynchronous Mutation Engine. - [Finding candidates](https://docs.onderwijsregio.onderwijsin.nl/raw/candidates/finding-candidates.md): List, search, and retrieve candidates in your region, including optional candidate self-access through authenticated sessions. - [Updating candidates](https://docs.onderwijsregio.onderwijsin.nl/raw/candidates/updating-candidates.md): Update candidate records with patch semantics, archive records for privacy, and permanently delete exceptional test or invalid data. - [Interactions](https://docs.onderwijsregio.onderwijsin.nl/raw/candidates/interactions.md): List, create, update, and delete candidate interactions using the asynchronous Onderwijsregio API. - [Attachments](https://docs.onderwijsregio.onderwijsin.nl/raw/candidates/uploading-attachments.md): Add, remove, and validate candidate attachments through dedicated asynchronous API endpoints. - [MCP Server](https://docs.onderwijsregio.onderwijsin.nl/raw/agents/mcp-server.md): Give AI agents read-only access to the Onderwijsregio API documentation and reference. - [LLMs.txt](https://docs.onderwijsregio.onderwijsin.nl/raw/agents/llms-txt.md): Give AI tools a focused or complete text version of the Onderwijsregio API documentation. - [Troubleshooting](https://docs.onderwijsregio.onderwijsin.nl/raw/misc/troubleshooting.md): Resolve common Onderwijsregio API integration issues, including rate limits, schema latency, record errors, and attachment uploads. - [Upgrade guide](https://docs.onderwijsregio.onderwijsin.nl/raw/misc/migration-guide.md): Follow the required and optional steps to migrate an existing Onderwijsregio API Version 1 integration to Version 2. - [Compliance](https://docs.onderwijsregio.onderwijsin.nl/raw/misc/compliance.md): Find the data-processing and sub-processor annexes relevant to integrations with the Onderwijsregio API. - [Getting started](https://docs.onderwijsregio.onderwijsin.nl/raw/version-1/getting-started.md): Understand the legacy Version 1 Onderwijsregio API before building or maintaining an existing integration. - [Authentication](https://docs.onderwijsregio.onderwijsin.nl/raw/version-1/authentication.md): Send the legacy Version 1 API key header when maintaining an existing Onderwijsregio API integration. - [Schema](https://docs.onderwijsregio.onderwijsin.nl/raw/version-1/schema.md): Review the legacy Version 1 candidate schema, including shared fields, interactions, and region-specific custom fields. - [Submitting a candidate](https://docs.onderwijsregio.onderwijsin.nl/raw/version-1/submitting-a-candidate.md): Maintain legacy Version 1 candidate submissions through the /create-user endpoint, including interactions and custom fields. - [Troubleshooting](https://docs.onderwijsregio.onderwijsin.nl/raw/version-1/troubleshooting.md): Understand legacy Version 1 response-time variability and choose resilient client timeouts for existing integrations. ## Api - [Onderwijsregio API](https://docs.onderwijsregio.onderwijsin.nl/raw/info.md): This API is part of a shared digital infrastructure developed by and for education regions (onderwijsregio’s) to track and support prospective teachers and other education professionals throughout their journey—from initial orientation to their start in education. - [DELETE /auth/regions/api-keys/{id}](https://docs.onderwijsregio.onderwijsin.nl/raw/auth/regions/api-keys/{id}.md): Deletes an API key for the specified region. Deletion is prevented if it is the only API key remaining for the region. - [DELETE /candidates/{id}](https://docs.onderwijsregio.onderwijsin.nl/raw/candidates/{id}.md): Permanently deletes a candidate by ID. The record will no longer be included in historical reporting and cannot be restored. **Warning:** In most cases you should archive a candidate instead. - [DELETE /candidates/{id}/interactions/{interactionId}](https://docs.onderwijsregio.onderwijsin.nl/raw/candidates/{id}/interactions/{interactionId}.md): Deletes an interaction by its ID. - [DELETE /regions/{id}](https://docs.onderwijsregio.onderwijsin.nl/raw/regions/{id}.md): Deletes a region. **Admin-only endpoint.** - [GET /auth/candidates/me](https://docs.onderwijsregio.onderwijsin.nl/raw/auth/candidates/me.md): Returns information about the currently authenticated candidate based on the active session. - [GET /auth/regions/me](https://docs.onderwijsregio.onderwijsin.nl/raw/auth/regions/me.md): Returns information about the currently authenticated region. Admin-scoped API keys may use the optional region query parameter to simulate requests for a specific region. - [GET /candidates](https://docs.onderwijsregio.onderwijsin.nl/raw/candidates.md): Lists candidates belonging to the authenticated region. Results are paginated using a cursor-based pagination strategy. - [GET /candidates/find](https://docs.onderwijsregio.onderwijsin.nl/raw/candidates/find.md): Finds candidates within the authenticated region by email address or phone number. At least one of `email` or `phone` must be provided. If both email and phone are provided, email is used for the search. - [GET /candidates/{id}](https://docs.onderwijsregio.onderwijsin.nl/raw/candidates/{id}.md): Retrieves a single candidate by ID within the authenticated region. Returned fields can be limited using the `fields` query parameter. By default, all standard shared fields are returned, excluding interactions and custom fields. Interactions can be optionally included. - [GET /candidates/{id}/interactions](https://docs.onderwijsregio.onderwijsin.nl/raw/candidates/{id}/interactions.md): Lists interaction records belonging to a specific candidate within the authenticated region. - [GET /candidates/{id}/interactions/{interactionId}](https://docs.onderwijsregio.onderwijsin.nl/raw/candidates/{id}/interactions/{interactionId}.md): Retrieves a single interaction record by its ID within the authenticated region. - [GET /regions](https://docs.onderwijsregio.onderwijsin.nl/raw/regions.md): Returns all regions along with their associated API keys. **Admin-only endpoint.** - [GET /schema](https://docs.onderwijsregio.onderwijsin.nl/raw/schema.md): Returns a region-specific, standards-compliant JSON Schema describing the request body for creating or updating a candidate. The schema is generated dynamically from the same validation logic used by the API and can be used for validation, form generation, or structured outputs. - [PATCH /candidates/{id}](https://docs.onderwijsregio.onderwijsin.nl/raw/candidates/{id}.md): Updates an existing candidate by ID. All fields in the request body are optional, but at least one field must be provided. Inline creation of interactions is not supported via this endpoint. For region-based authentication, ownership of the candidate is not pre-validated at request time. If the candidate does not belong to the region, the mutation engine will reject the operation and propagate the error to the callback URL if provided. - [PATCH /candidates/{id}/interactions/{interactionId}](https://docs.onderwijsregio.onderwijsin.nl/raw/candidates/{id}/interactions/{interactionId}.md): Updates an existing interaction by its ID. At least one field must be provided in the request body. - [PATCH /regions/{id}](https://docs.onderwijsregio.onderwijsin.nl/raw/regions/{id}.md): Partially updates a region. **Admin-only endpoint.** - [POST /auth/candidates/request-email-verification](https://docs.onderwijsregio.onderwijsin.nl/raw/auth/candidates/request-email-verification.md): Initiates an email-based identity verification flow for a candidate. If the email address matches one or more candidates, a verification link is sent to the email address. - [POST /auth/regions/api-keys](https://docs.onderwijsregio.onderwijsin.nl/raw/auth/regions/api-keys.md): Creates a new API key for the specified region. The full API key is returned **only once** and must be stored securely. Subsequent requests will only expose a preview. - [POST /candidates](https://docs.onderwijsregio.onderwijsin.nl/raw/candidates.md): Creates one or more candidates for the authenticated region. Supports chained creation of interactions, custom fields, attachments, sandbox mode, and asynchronous processing via the Mutation Engine. - [POST /candidates/{id}/archive](https://docs.onderwijsregio.onderwijsin.nl/raw/candidates/{id}/archive.md): Archives (anonymizes) a candidate by ID. On successful archival, the candidate record is permanently unretrievable. If a `callbackUrl` is provided, a copy of the candidate record *before archival* will be sent to the callback endpoint. For region-based authentication, ownership is not pre-validated at request time. If the candidate does not belong to the region, the mutation engine will reject the operation and propagate the error to the callback URL if provided. - [POST /candidates/{id}/attachments](https://docs.onderwijsregio.onderwijsin.nl/raw/candidates/{id}/attachments.md): Uploads one or more attachments and links them to an existing candidate record. The candidate must exist and belong to the authenticated region. Existing attachments on the candidate are preserved; new attachments are appended. At least one attachment field (`curriculumVitae` or `otherAttachments`) must be provided. - [POST /candidates/{id}/attachments/delete](https://docs.onderwijsregio.onderwijsin.nl/raw/candidates/{id}/attachments/delete.md): Removes one or more attachments from an existing candidate record. At least one attachment must be specified, either in `curriculumVitae` or `otherAttachments`. Authorization to the candidate record is enforced before the mutation is accepted. - [POST /candidates/{id}/interactions](https://docs.onderwijsregio.onderwijsin.nl/raw/candidates/{id}/interactions.md): Creates one or more interactions for a specific candidate. A maximum of 10 interactions can be created in a single request. For region-based authentication, ownership of the candidate is not pre-validated at request time. If the candidate does not belong to the region, the mutation engine will reject the operation and propagate the error to the callback URL if provided. - [POST /candidates/upsert](https://docs.onderwijsregio.onderwijsin.nl/raw/candidates/upsert.md): Creates or updates a candidate. If a candidate with the same email (case-insensitive) or phone number (normalized) already exists, the candidate will be updated. Otherwise, a new candidate will be created. ⚠️ Custom fields are only applied when creating a new candidate, not when updating an existing one. - [POST /regions](https://docs.onderwijsregio.onderwijsin.nl/raw/regions.md): Creates a new region. **Admin-only endpoint.** - [POST /webhooks/regions](https://docs.onderwijsregio.onderwijsin.nl/raw/webhooks/regions.md): Processes an Airtable webhook event for region data changes and upserts the corresponding region record. Requires a webhook-scoped API key. - [AirtableAttachment](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/airtableattachment.md): Attachment object as returned by the Airtable API. - [AirtableThumbnail](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/airtablethumbnail.md): Thumbnail - [ApiKey](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/apikey.md): ApiKey - [ApiKeyCreate](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/apikeycreate.md): API key creation payload. Admin-scoped API keys may optionally supply a custom API key value. - [ApiKeyCreateForAdmin](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/apikeycreateforadmin.md): ApiKeyCreateForAdmin - [ApiKeyCreateForRegion](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/apikeycreateforregion.md): ApiKeyCreateForRegion - [AttachmentCreatePayload](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/attachmentcreatepayload.md): Payload used to add attachments to an existing candidate. At least one of `curriculumVitae` or `otherAttachments` must be provided and contain at least one item. - [AttachmentDeletePayload](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/attachmentdeletepayload.md): Payload used to remove attachments from an existing candidate. At least one of `curriculumVitae` or `otherAttachments` must be provided and contain at least one item. - [AttachmentPayload](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/attachmentpayload.md): Attachment provided by the client, either via URL or base64-encoded data. - [BadRequestErrorResponse](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/badrequesterrorresponse.md): BadRequestErrorResponse - [BaseResponseMeta](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/baseresponsemeta.md): BaseResponseMeta - [Candidate](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/candidate.md): Candidate record as returned by the API. - [CandidateBase](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/candidatebase.md): Base candidate fields shared across create, update, and output variants. - [CandidateCreate](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/candidatecreate.md): Payload used to create a new candidate. - [CandidateJsonSchema](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/candidatejsonschema.md): A standards-compliant JSON Schema document describing the request payload for creating or updating a candidate. - [CandidatePhase](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/candidatephase.md): Phase the candidate is currently in. - [CandidateUpdate](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/candidateupdate.md): Payload used to update an existing candidate. At least one field must be provided. - [CandidateWithInteractions](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/candidatewithinteractions.md): CandidateWithInteractions - [ErrorResponse](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/errorresponse.md): Error - [GenericErrorData](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/genericerrordata.md): GenericErrorData - [Interaction](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/interaction.md): Interaction record as returned by the API. - [InteractionBase](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/interactionbase.md): Base interaction fields shared across create and output variants. - [InteractionCreate](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/interactioncreate.md): Payload used to create an interaction. - [InteractionType](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/interactiontype.md): Type of interaction associated with a candidate. - [InteractionUpdate](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/interactionupdate.md): Payload used to update an interaction. - [MutationEngineAccepted](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/mutationengineaccepted.md): MutationEngineAccepted - [PaginationMeta](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/paginationmeta.md): PaginationMeta - [PriorEducation](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/prioreducation.md): The highest level of education the candidate has completed. - [Qualification](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/qualification.md): Qualification that the candidate wants to obtain. - [Region](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/region.md): Region - [RegionCreate](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/regioncreate.md): RegionCreate - [RegionEditable](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/regioneditable.md): RegionEditable - [RegionUpdate](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/regionupdate.md): RegionUpdate - [RegionWebhookPayload](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/regionwebhookpayload.md): RegionWebhookPayload - [RegionWithApiKeys](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/regionwithapikeys.md): RegionWithApiKeys - [Role](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/role.md): Role, job, or position in education. - [Sector](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/sector.md): Educational sector. - [Session](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/session.md): Session - [StaticCustomFields](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/staticcustomfields.md): Custom candidate fields defined per region. - [Subject](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/subject.md): Subject that the candidate is interested in. - [SuccessResponse](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/successresponse.md): SuccessResponse - [ValidationErrorData](https://docs.onderwijsregio.onderwijsin.nl/raw/schemas/validationerrordata.md): ValidationErrorData - [Admin](https://docs.onderwijsregio.onderwijsin.nl/raw/tags/admin.md): Admin-only endpoints for managing regions and system-level configuration. - [Attachments](https://docs.onderwijsregio.onderwijsin.nl/raw/tags/attachments.md): Upload and remove attachments linked to candidates. - [Auth](https://docs.onderwijsregio.onderwijsin.nl/raw/tags/auth.md): Authentication and identity verification endpoints for candidates and regions. - [Candidates](https://docs.onderwijsregio.onderwijsin.nl/raw/tags/candidates.md): Managing candidate data for your region. - [Interactions](https://docs.onderwijsregio.onderwijsin.nl/raw/tags/interactions.md): Managing interaction records linked to candidates. - [Regions](https://docs.onderwijsregio.onderwijsin.nl/raw/tags/regions.md): Region info, authentication, configuration, and API key management. - [Schema](https://docs.onderwijsregio.onderwijsin.nl/raw/tags/schema.md): Retrieve the dynamic candidate field schema for your region. - [Webhooks](https://docs.onderwijsregio.onderwijsin.nl/raw/tags/webhooks.md): Inbound webhook endpoints authenticated using webhook-scoped API keys.