Submitting a candidate

Learn how to create or update a candidate within the applicant tracking system (ATS) of your education region.

This guide explains how to call the /create-user endpoint, how to structure the payload, and how the API processes candidate data.

Endpoint overview

To submit a candidate, send a POST request to:

https://onderwijsregio.onderwijsin.nl/api/v1/create-user

Each request must include:

• An api-key header
• A request body encoded as application/json

Upsert behavior

As of API version 1.1.0, the /create-user endpoint uses upsert logic.

• The candidate’s email address is used as the unique identifier.
• If a candidate with the same email already exists, the existing record is updated.
• If multiple records with the same email exist, only the first match is updated.

This allows you to safely resend data for the same candidate without creating duplicates.

Request payload

The request body contains the candidate data. The minimum required fields are:

• naam
• email
• privacy_consent

All other fields are optional and may be included depending on your use case and region configuration.

The payload must conform to the schema returned by the /schema endpoint.

Supported field values

Some fields only accept predefined values. The most important standardized options are listed below.

nieuw
matchen
oriënteren
voorbereiden
in opleiding
werkzaam
uitgestroomd

Primair onderwijs
Voortgezet onderwijs
Speciaal onderwijs
Middelbaar beroepsonderwijs
Hoger onderwijs
Praktijkonderwijs

Docent / leraar
Instructeur (mbo)
OOP
Ondersteuning
Leerlingenzorg
Midden management
Schoolleiding
Anders

Primair onderwijs
Beperkt tweedegraads
Tweedegraads
Eerstegraads
PDG
BKO/BDB
Kwalificatie onderwijs ondersteunend personeel
Kwalificatie Instructeur (MBO)
Geen: gastdocentschap
Pabo
Onbekend
Nog geen idee
Niet van toepassing

geen
praktijkonderwijs
vmbo-bl
vmbo-kl
vmbo-gl
vmbo-tl
vmbo
havo
vwo
mbo entree
mbo 2
mbo 3
mbo 4
mbo
associate degree
hbo propedeuse
hbo bachelor
hbo master
hbo
wo bachelor
wo master
wo
PhD

Telefonisch
E-mail
Persoonlijk
Anders
Doorverwijzing
Adviesgesprek
Kennismakingsgesprek
Inschrijving activiteit
Niet van toepassing

Always refer to the /schema endpoint for the authoritative and most up-to-date list of allowed values.

Interactions

You can optionally include one or more interactions when submitting a candidate. This is useful when a candidate submits their details as part of an activity or contact moment.

• Interactions can be sent as a single object or an array.
• Each interaction requires at least a date and one or more interaction types.

A legacy single-interaction field is still supported for backward compatibility. It is preferred to use the interacties property.

Custom fields

In addition to the shared schema, regions may define custom fields. These fields are unique per region and are sent as an array under custom_fields.

Each custom field consists of:

• field_name: the exact name from the schema
• field_value: the value for that field

If your payload contains custom fields that are not defined for your region, they are ignored and do not cause the request to fail. Valid custom fields in the same payload are still processed.

Use the /schema endpoint to discover which custom fields are available for your region.

Example request

POST https://onderwijsregio.onderwijsin.nl/api/v1/create-user
Content-Type: application/json
api-key: <your-api-key>

{
  "naam": "Pietje Puk",
  "email": "pietjepuk@onderwijsin.nl",
  "privacy_consent": true,
  "fase": "nieuw",
  "interacties": {
    "datum": "2024-07-05",
    "soort": ["Inschrijving activiteit"],
    "samenvatting": "Aanmelding voor informatieavond"
  },
  "custom_fields": [
    {
      "field_name": "Voorkeur vak",
      "field_value": "Wiskunde"
    }
  ]
}

Responses

Unauthorized

{
  "statusCode": 401,
  "statusMessage": "Not authorized",
  "message": "Invalid api key"
}

Invalid payload

{
  "statusCode": 400,
  "statusMessage": "Bad request",
  "message": "Please check your request body.",
  "data": {
    "errors": ["Detailed validation errors"]
  }
}

Server error

{
  "statusCode": 500,
  "statusMessage": "Server error",
  "message": "Something went wrong creating the record. Please try again."
}

Success

{
  "statusCode": 200,
  "message": "Candidate was created successfully",
  "data": {
    "candidate": {
      "id": "recGHIjkl12345",
      "name": "Test",
      "email": "test@onderwijsin.nl",
      "phase": "nieuw",
      "privacy_consent": true,
      "regions": {
        "count": 1,
        "ids": ["recABCdef12345"],
        "origin": ["recABCdef12345"]
      },
      "timestamps": {
        "created_at": "2025-12-19T16:57:19.000Z",
        "original_created_at": "2025-12-19T16:57:19.136Z",
        "updated_at": "2025-12-19T17:10:49.000Z"
      },
      "created_by": {
        "id": "usrABCdef12345",
        "name": "Onderwijs in",
        "email": "jacob@onderwijsin.nl"
      },
      "updated_by": {
        "id": "usrABCdef12345",
        "name": "Onderwijs in",
        "email": "jacob@onderwijsin.nl"
      },
      "custom_fields": {
        "vakken": ["wiskunde"]
      }
    },
    "interactions": [
      {
        "name": "Telefonisch - 2023-01-01",
        "type": ["Telefonisch"],
        "summary": "Ingeschreven voor de activiteit XYZ",
        "performed_at": "2023-01-01T00:00:00.000Z",
        "created_at": "2025-12-19T22:42:59.000Z",
        "created_by": {
          "id": "usrABCdef12345",
          "name": "Onderwijs in",
          "email": "jacob@onderwijsin.nl"
        }
      }
    ]
  }
}