Candidates

Finding candidates

List, search, and retrieve candidates in your region, including optional candidate self-access through authenticated sessions.

Choose the right API endpoint to list, search, or retrieve candidate records.

This section describes the different ways you can retrieve and search candidate data using the Onderwijsregio API. Depending on your use case—bulk access, targeted lookup, or candidate self-access—different endpoints are available.

Choose a discovery method

The API exposes three primary ways to find candidates:


Method	Endpoint	Typical use case
List candidates	`GET /candidates`	Browse or sync all candidates in a region
Find by identifier	`GET /candidates/find`	Look up candidates by email or phone
Fetch by ID	`GET /candidates/{id}`	Retrieve a specific candidate record

All endpoints described below operate within the authenticated region and support sandbox mode via the x-api-sandbox header.

List candidates in bulk

Use GET /candidates to retrieve all candidates belonging to your region. This endpoint is designed for integrations that need to synchronize or browse candidate data.

Key characteristics:

Cursor-based pagination.
Optional field selection.
Region-scoped access through API-key authentication.
Rate limits apply.
A maximum pageSize of 100 records.

GET /candidates?pageSize=10&cursor=abc123

The response includes:

data: an array of candidate records
meta.cursor: a cursor for fetching the next page (or null if finished)

Follow the cursor until it becomes null to retrieve the complete dataset.

Find candidates by email or phone

For targeted lookups, use GET /candidates/find. This endpoint allows you to search for candidates using email address or phone number.

Rules:

At least one of email or phone must be provided
If both are supplied, email takes precedence
Email matching is case-insensitive
Phone numbers ignore non-numeric characters

GET /candidates/find?email=jane.doe@example.com

This method is ideal for:

Finding records based on user input
Resolving inbound leads
Matching external systems to existing records

Retrieve a candidate by ID

Once you know a candidate’s unique identifier, you can retrieve the full record using GET /candidates/{id}.

Features:

Supports both API key and candidate session authentication
Optional field filtering
Optional inclusion of interaction records

GET /candidates/recAbC13pTbjpS6Iz?includeInteractions=true

By default all fields are returned that are part of the candidates table. (Related) interactions must be explicitly requested.

Limit returned fields

Most candidate endpoints support the fields query parameter. This allows you to limit responses to only the data you need, improving performance and reducing payload size.

GET /candidates?fields=name&fields=email&fields=phase

If omitted, all standard shared fields are returned (excluding interactions and custom fields).

Enable candidate self-access

Candidates themselves can retrieve their own records using GET /auth/candidates/me. This endpoint relies on a session bearer token, not an API key.

Use cases include:

Candidate portals
Self-service dashboards
Verification flows

The response may include multiple candidate records if the session (e.g. email) is linked to more than one candidate.

A candidate can also access their own data via /candidates/{id} with session authentication.

Test discovery flows in the sandbox

All candidate discovery endpoints support sandbox mode via:

The x-api-sandbox: true header, or
The /sandbox endpoint prefix

This allows you to test candidate search flows without affecting production data.

Submitting candidates

Create or upsert candidates, including interactions and attachments, through the asynchronous Mutation Engine.

Updating candidates

Update candidate records with patch semantics, archive records for privacy, and permanently delete exceptional test or invalid data.