Before creating a candidate via the /create-user endpoint, you should retrieve the schema for your region using the /schema endpoint. This endpoint returns the complete, region-specific definition of all fields that are accepted in the candidate payload.

The schema is authoritative: it describes which fields are available, which are required, which values are allowed, and how nested or related data must be structured. You should always base your payload construction and validation on the response of this endpoint.

The /schema endpoint

The schema response is tailored to the authenticated region and consists of three main parts:

1. Shared fields

2. Interactions

3. Custom fields

Together, these define the full shape of the payload accepted by /create-user.

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:

• fieldName: the name to use in the request payload

• fieldType: the expected data type (for example string, array, boolean)

• required: whether the field is mandatory

• options (optional): a list of allowed values for enumerated fields

• fieldDescription: a human-readable explanation of the field

Examples of shared fields include candidate identity data, consent flags, current phase, sector preferences, qualifications, and contact details. If a field defines an options array, the provided value must match one of the allowed options exactly.

Required shared fields must always be present in the payload. Optional fields may be omitted entirely.

Interactions

Interactions represent contact moments or events related to a candidate, such as phone calls, emails, or attendance. Interactions are a related resource, but they can be created as part of the same payload when creating or updating a candidate.

The schema supports:

• A single interaction object

• An array of interaction objects

Each interaction definition specifies:

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

• Allowed interaction types

• Optional descriptive fields (such as a summary)

The schema stills exposes a legacy single-interaction field (interactie0 for backward compatibility. The plural form (interacties) should be preferred.

Custom fields

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

Key characteristics of custom fields:

• They are returned as a sub-schema inside the custom_fields definition

• They are dynamically generated based on the authenticated API key

• Their structure and allowed values can differ per region

In the payload, custom fields are always sent as an array of objects with:

• field_name: the exact name of the custom field as defined in the schema

• field_value: the value for that field

The schema defines, per custom field:

• Whether the field is required

• The expected data type

• Allowed options (if applicable)

• A description of its intended use

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

How to use the schema

The schema is primarily intended as a development and discovery tool, allowing you to explore the data model and available custom fields for your region. While it can technically be used at runtime to dynamically construct payloads, this is not a strict requirement.

Validation of custom fields is intentionally lenient. If your payload contains custom field entries or properties that are not defined in the schema, they will be ignored rather than causing the request to fail. Custom fields for a region change infrequently, and sending invalid or outdated custom fields will not break your request.