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.

The schema defines:

• Which fields are available

• Which fields are required

• Which values are allowed

• How arrays, nested objects, and related data must be structured

You should always base payload construction and validation on the response of this endpoint.

The /schema endpoint

The schema returned by /schema is scoped to the authenticated region and consists of three parts:

• Shared fields

• Interactions

• Custom fields

Together, these define the complete payload shape accepted by /candidates/** endpoints.

Shared fields

Shared fields are standardized across all education regions. They represent the core candidate data model and are always present in the schema.

Each shared field definition includes:

• name
  The key to use in the request payload.

• type
  The expected data type (string, number, boolean, array, object, or objectArray).

• required
  Whether the field must be present in the payload when creating a candidate.

• options (optional)
  A list of allowed values for enumerated fields. When provided, values must match exactly.

• description (optional)
  A human-readable explanation of the field’s purpose.

Examples of shared fields include candidate identity data, consent flags, current phase, sector and role preferences, qualifications, and contact information.

Required shared fields must always be present in the payload when creating a candidate. Patching an existing candidate always accepts a partial payload. Optional fields may be omitted entirely in any case.

Interactions

Interactions represent contact moments or events related to a candidate, such as phone calls, emails, meetings, or other forms of engagement.

Interactions are modeled as an objectArray field, meaning the payload may include zero or more interaction objects when creating or updating a candidate.

Each interaction definition specifies:

• Required properties (such as the interaction date and type)

• Allowed interaction types

• Optional descriptive fields (such as a summary, notes, or duration)

Each interaction object is created and linked to the candidate. Existing interactions are not replaced unless explicitly updated through a dedicated endpoint.

Custom fields

Custom fields are region-specific extensions to the shared schema. They allow education regions to capture additional data that is not standardized across all regions.

Key characteristics of custom fields:

• They are returned as a nested schema inside the customFields definition

• They are dynamically generated based on the authenticated API key

• Their structure, data types, and allowed values may differ per region

In the schema, custom fields are defined in the same way as shared fields, including:

• Whether the field is required

• The expected data type

• Allowed options (if applicable)

• A description of its intended use

Custom fields may be of any supported primitive or array type.

Your integration must treat the custom fields schema as dynamic and must not assume a fixed or global set of custom fields across regions.

How to use the schema

The schema is primarily intended as a development and discovery tool. It allows you to:

• Explore the candidate data model

• Discover region-specific custom fields

• Validate payloads during development and integration

While the schema can technically be used at runtime to dynamically construct payloads or user interfaces, this is not required.

Validation of custom fields is intentionally lenient:

• Unknown or outdated custom fields are ignored

• Invalid custom field values do not cause the request to fail

• Custom fields change infrequently and are designed not to break existing integrations

For best results, retrieve and review the schema during development and update your integration when schema changes are introduced.