Werken met de Onderwijsregio API: kandidaten integreren in een gedeelde infrastructuur

Steeds meer onderwijsregio’s nemen deel het project waar we een gedeelde digitale infrastructuur hebben opgezet om (zij-)instromers beter te volgen en te begeleiden. Binnen deze infrastructuur speelt de API een belangrijke rol: als verbindende laag tussen het kandidaatvolgsysteem (ATS) en de verschillende tools die regio’s gebruiken, zoals websites en formulieren.

Met de API kunnen regio’s kandidaatdata vanuit uiteenlopende bronnen op een consistente manier samenbrengen. Zo ontstaat één actueel overzicht van kandidaten, hun voortgang en hun ondersteuningsbehoefte.

Eén infrastructuur, verbonden met jouw systemen

Onderwijsregio’s werken met verschillende systemen om potentiële kandidaten te bereiken. Denk aan regiowebsites, aanmeldformulieren of campagnesystemen. In de praktijk leidt dit vaak tot versnippering: gegevens staan op meerdere plekken en zijn niet altijd actueel.

De digitale infrastructuur brengt dit samen in één centrale omgeving. De API maakt het mogelijk om externe systemen hier direct op aan te sluiten.

Een aanmelding via een regiowebsite kan zo automatisch worden doorgestuurd naar het ATS, inclusief relevante gegevens zoals voorkeuren of contactmomenten. Dit voorkomt handmatig werk en zorgt dat kandidaten direct in beeld zijn.

Wat je met de API kunt

De API ondersteunt verschillende toepassingen, afhankelijk van hoe een regio haar processen heeft ingericht.

Kandidaten toevoegen

De meest gebruikte toepassing is het toevoegen van nieuwe kandidaten vanuit externe systemen, zoals formulieren op een website. Hierbij kun je niet alleen basisgegevens doorgeven, maar ook aanvullende informatie zoals:

• interessegebieden of sectorvoorkeuren

• eerste contactmomenten (bijvoorbeeld een intakegesprek)

• bijlagen zoals een CV

Deze informatie wordt direct onderdeel van het kandidaatsdossier in het ATS, zodat begeleiders meteen over de juiste context beschikken.

Aanvullende toepassingen

Naast het aanmaken van kandidaten ondersteunt de API ook:

• het bijwerken en verwijderen van bestaande kandidaatgegevens

• het doorzoeken van kandidaatdossier

• het vastleggen van interacties

• het synchroniseren van data tussen systemen

Zo kan de API verschillende rollen vervullen binnen de verschillende processen die binnen regio's worden ingericht.

Flexibel datamodel per regio

Een belangrijk uitgangspunt van de infrastructuur is dat regio’s verschillend werken — en dat systemen daarop moeten aansluiten. Daarom is gekozen voor een hybride datamodel:

• een gedeelde basis met vaste velden en definities

• aangevuld met regio-specifieke velden

Hoe dit werkt in de API

Elke regio heeft een eigen schema dat via de API beschikbaar is. Dit schema beschrijft precies:

• welke velden beschikbaar zijn

• welke gegevens verplicht zijn

• welke waarden toegestaan zijn

Dit schema sluit direct aan op de validatie in de API zelf. Als data voldoet aan het schema, wordt deze ook geaccepteerd.

Waarom dit belangrijk is

Deze aanpak zorgt voor een balans tussen standaardisatie en flexibiliteit:

• regio’s kunnen hun eigen werkwijze blijven volgen

• terwijl data toch op een consistente manier wordt opgeslagen en gedeeld

Voor integraties betekent dit dat je niet werkt met een vast, vooraf gedefinieerd model, maar met een dynamische structuur per regio. Dat maakt koppelingen toekomstbestendig en beter afgestemd op de praktijk.

Ontwerpkeuzes: waarom de API werkt zoals hij werkt

Bij het ontwerpen van de API is nadrukkelijk gekeken naar betrouwbaarheid, gebruiksgemak en schaalbaarheid.

Asynchrone verwerking als bewuste keuze

Alle wijzigingen (zoals het aanmaken of bijwerken van kandidaten) worden asynchroon verwerkt. Dat betekent dat een verzoek eerst wordt gevalideerd en in een wachtrij geplaatst, waarna de verwerking op de achtergrond plaatsvindt.

Deze keuze is bewust gemaakt om goed om te gaan met eigenschappen van onderliggende systemen, zoals de beperkingen en soms onvoorspelbare responstijden van de Airtable API.

Dit heeft twee belangrijke voordelen:

• Een betere gebruikerservaring: verzoeken worden snel geaccepteerd, zonder wachttijden of timeouts

• Een betere developer experience: integraties hoeven geen rekening te houden met instabiel gedrag of piekbelasting

Andere ontwerpprincipes

• Validatie via het schema zorgt voor voorspelbaar gedrag

• Scheiding per regio borgt dat data veilig en afgebakend blijft

• Idempotente verzoeken maken integraties robuust bij retries of netwerkproblemen

Hoe een integratie er conceptueel uitziet

Hoewel elke integratie anders is, volgt de basis meestal dezelfde stappen:

1. Je haalt het schema van de regio op

2. Je richt je formulier of systeem in op basis van dit schema

3. Je verstuurt kandidaatdata via de API

4. De infrastructuur verwerkt de gegevens en maakt ze beschikbaar in het ATS

Optioneel kun je gebruikmaken van callbacks om terugkoppeling te krijgen over de verwerking.

Ontwikkelen en testen

Voor het ontwikkelen van integraties is een sandbox-omgeving beschikbaar. Deze werkt hetzelfde als de productieomgeving, maar zonder impact op echte data.

Dit maakt het mogelijk om:

• koppelingen veilig op te zetten

• verschillende scenario’s te testen

• iteratief te ontwikkelen en verbeteren

Samen verder ontwikkelen

De API is onderdeel van een bredere, gezamenlijke infrastructuur die continu wordt doorontwikkeld. Regio’s spelen hierin een actieve rol: hun ervaringen en behoeften vormen de basis voor nieuwe functionaliteiten.

We zijn ook benieuwd naar hoe regio’s de API in de praktijk gebruiken. Van maatwerkformulieren tot slimme koppelingen met andere systemen — deze toepassingen helpen om het platform verder te verbeteren.

Aan de slag

Wil je zelf aan de slag met de API of verkennen wat er mogelijk is?

• Bekijk de developer documentatie en de interactieve API explorer

• Of lees meer over het project en hoe jouw regio kan aansluiten

Zo bouwen we samen verder aan een infrastructuur die werkt voor én met onderwijsregio’s.