Finding Candidates

Learn of the different methods by which you can search through the data set.

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.

Overview of Available Methods

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.

Listing Candidates (Bulk Access)

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 via API key authentication
Rate limits apply
Max pageSize of 100 record

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)

Pagination required
Always follow the cursor until it becomes null to ensure you retrieve the full dataset.

Finding 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

Retrieving 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.

Limiting 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).

Candidate Self-Access (Authenticated Sessions)

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.

Sandbox Support

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.