Association API

Titel	Association API
Status	In ontwikkeling ROSA-Architectuurscan BEsluitvorming implementatie in beheer
Versie	Documentatie: 1.0.1
Versie	schemaVersion: 1.0.1
Datum	9 Oktober 2025
Auteurs	Werkgroep Doorgifte Administratie
Acties	Review en doorontwikkeling op basis van input LAS leveranciers

De Association API wordt gebruikt om informatie over uit het Administratiesysteem onderwijsdeelnemer te delen in het Afsprakenstelsel Edu-V. Deze API wordt aangeboden als onderdeel van de gegevensdienst Onderwijsinrichting met het Administratiesysteem onderwijsdeelnemer als Bron.

Scope: werkingsgebieden funderend onderwijs en vavo

De afspraken met betrekking tot de gegevensdiensten uit de administratiesystemen zijn van toepassing op de werkingsgebieden:

Primair onderwijs
Gespecialiseerd onderwijs
Voortgezet onderwijs
Voortgezet algemeen volwassenenonderwijs (vavo)

De gegevensdiensten zijn niet ontwikkeld voor het middelbaar beroepsonderwijs. In het middelbaar beroepsonderwijs wordt gebruik gemaakt van OOAPI.

De technische specificatie bestaat uit:

1 Samenvatting
2 Object: SchoolPeriod (SchoolPeriode)
3 Object: Enrollment (Inschrijving)
4 Object: referentie Locatie
5 Object: Assignment (Toewijzing)
6 Object: Group (Stamgroep of Lesgroep)
7 Event processor: Aanspraakmanager
8 Status- en foutcodes
9 Technisch: API specificatie
10 Release notes

Samenvatting

Gegevensdienst	Onderwijsinrichting
Scopes	eduv.association
Entiteiten	SchoolPeriod Enrollment Assignment Group
Bron	Administratiesysteem onderwijsdeelnemer
Afnemer	Bestelomgeving leermiddelen Aanspraakmanager Identitietsbeheervoorziening
Endpoints	Administratiesysteem onderwijsdeelnemer GET SchoolPeriod GET SchoolPeriods for School GET Enrollment GET Enrollments for School POST Get Enrollments for Student at School GET Assignment GET Assignments for School POST Get Assignments for Employee at School GET Group GET Group for School
Notifications	De Notifications API kan gebruikt worden om als afnemer een notificatie te ontvangen bij een wijziging in de stand (nieuw/gewijzigd/verwijderd). Hiervoor dient zowel de bron als de afnemer dan de Berichteninfrastructuur en de Notifications API te hebben geïmplementeerd. Berichteninfrastructuur voor het versturen en ontvangen van berichten Notifications API

Object: SchoolPeriod (SchoolPeriode)

Het object SchoolPeriod beschrijft de periodes waarin onderwijs wordt gegeven binnen de onderwijsaanbieder. De velden uit het object zijn gebaseerd op een AcademicSession zoals ook beschreven in de internationale 1EdTech standaard OneRoster.

Optioneel

De gelaagde structuur van schoolperiodes is optioneel voor de Association API. Op basis van expliciete behoeften van onderwijsaanbieders en/of ketenprocessen kunnen schoolperiodes benut worden.

In de eerste versie voldoet een schoolperiode van het type schoolYear, bijvoorbeeld ‘23-’24.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
schoolPeriodId	string	string	Een unieke identifier voor het object		V	“startschooljaar-eindschooljaar” als het een schooljaar betreft en anders moet het veld worden gevuld met een UUID.
title	string	string	Naam van de schoolperiode	2021-2022 2022H1	V
type	string	ENUM	Het type schoolperiode. Hierbij wordt een ENUM gehanteerd bestaande uit: gradingPeriod schoolYear semester term	schoolYear	O	De waardelijst is overgenomen vanuit OneRoster voor SessionType van een AcademicSession.
superSchoolPeriod	string	string	Een referentie naar een bovenliggend SchoolPeriod object.		O	De superSchoolPeriod van een semester is bijvoorbeeld het schoolYear
subSchoolPeriod	array	string	Referenties naar onderliggende SchoolPeriod objecten.		O	De subSchoolPeriods van een schoolYear zijn bijvoorbeeld de semesters
startDate	string	date	Startdatum van de schoolperiode	2022-08-01	V
endDate	string	date	Einddatum van de schoolperiode	2023-07-31	V
status	string	ENUM	De status van dit object.	active tobedeleted	V	De status is een verplicht veld en geef aan of het object al dan niet verwijderd kan worden.
dateCreated	string	datetime	Datum en tijdstip waarop de entiteit is aangemaakt	2017-07-21T17:32:28Z	V
dateLastModified	string	datetime	Tijdstempel waarop één of meerdere van de hierboven genoemde attributen het laatst zijn gewijzigd	2022-08-11T15:31:12Z	V

Object: Enrollment (Inschrijving)

Het object Enrollment beschrijft de inschrijving van een onderwijsdeelnemer op een AangebodenOpleiding of een AangebodenVak voor een schoolperiode op een onderwijsaanbieder.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
enrollmentId	string	uuid	Een unieke identifier voor het object		V
student	object	UserReference	Een referentie naar een onderwijsdeelnemer.	Zie referentie Eindgebruiker	V
enrollmentType	string	ENUM	Het type inschrijving. Hierbij wordt een ENUM gehanteerd bestaande uit: `study` `subject`	`study`	V	Inschrijvingen op AangebodenOpleidingen worden minimaal beschikbaar gesteld. De vullingsregels voor inschrijvingen op vakken moet nog bepaald worden.
study	string	uuid	Een referentie naar een AangebodenOpleiding (StudyOffering) object waarop de onderwijsdeelnemer is ingeschreven.		V*	Verwijzing naar studyOfferingId Verplicht indien het enrollmentType `study` betreft.
studyPublicId	string	uuid	Een referentie naar een AangebodenOpleiding in RIO.		O	Verwijzing naar `id` in RIO.
studyYear	integer	integer	Het opleidingsjaar waarop deze Inschrijving van toepassing is.	1	V*	Verplicht indien het enrollmentType `study` betreft.
location	object	LocationReference	De locatie van de AangebodenOpleiding waar de Onderwijsdeelnemer op is ingeschreven.	Zie LocationReference	O
subject	string	uuid	Een referentie naar een AangebodenVak (SubjectOffering) object waarop de onderwijsdeelnemer is ingeschreven.		V*	Verwijzing naar subjectOfferingId Verplicht indien het enrollmentType `subject` betreft.
schoolPeriod	string	uuid	Een referentie naar een Schoolperiode (SchoolPeriod) object waarbinnen de inschrijving valt.		V	Verwijzing naar schoolPeriodId Waarde mag niet gewijzigd worden
beginDate	string	date	Begindatum van de inschrijving	2022-08-01	V	De begindatum van de inschrijving kan afwijken van de startdatum van de schoolperiode.
endDate	string	date	Einddatum van de inschrijving	2023-07-31	O	De einddatum is een verplicht veld indien de inschrijving eerder afloopt dan de schoolperiode.
status	string	ENUM	De status van dit object.	active tobedeleted	V	De status is een verplicht veld en geef aan of het object al dan niet verwijderd kan worden.
dateCreated	string	datetime	Datum en tijdstip waarop de entiteit is aangemaakt	2017-07-21T17:32:28Z	V
dateLastModified	string	datetime	Tijdstempel waarop één of meerdere van de hierboven genoemde attributen het laatst zijn gewijzigd	2022-08-11T15:31:12Z	V

Object: referentie Locatie

Een referentie naar een locatie bevat de primaire identifier (eerste voorkeur) en indien deze niet beschikbaar is door een uitzonderingssituatie een secundaire identifier.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
locationMasterIdentifier	string	string	De primaire identifier voor een locatie.	112X995	V*	De werkingsregels is dat de primaire identifier wordt gehanteerd in de berichten. De primaire identifier voor locatie is de onderwijslocatie (`OL_CODE`). In geval van een uitzonderingssituatie kan gebruik gemaakt van een secundaire identifier.
locationIds	array	locationId	Een lijst van secundaire identifiers die gehanteerd kan worden als de primaire identifier ontbreekt.	[{“locationId”: “string”, “locationIdType”: “VE_CODE”}]	V*	Zodra een secundaire identifier voor een uitzonderingssituatie gehanteerd wordt dan wordt naast het Id ook het Type gespecificeerd. De secundaire identifier voor locatie is de vestigingserkenning (`VE_CODE`).
name	string	string	Naam behorende bij de locatie.		V

Object: Assignment (Toewijzing)

Het object Assignment beschrijft de toewijzing van een onderwijsmedewerker aan een groep of individu voor een schoolperiode op een onderwijsaanbieder.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
assignmentId	string	string	Een unieke identifier voor het object		V
employee	object	UserReference	Een referentie naar een onderwijsmedewerker.	Zie referentie Eindgebruiker	V
assignmentType