Employees API

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

De Employees API wordt gebruikt om persoonsgegevens over onderwijsmedewerkers uit het Administratiesysteem onderwijsmedewer te delen in het Afsprakenstelsel Edu-V. Deze API wordt aangeboden als onderdeel van de gegevensdienst Onderwijsmedewerker met het Administratiesysteem onderwijsmedwerker 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: Employee (Onderwijsmedewerker)
3 Status- en foutcodes
4 Technisch: API specificatie
5 Release notes

Samenvatting

Gegevensdienst	Onderwijsmedewerkers Onderwijsmedewerkers Communicatie Onderwijsmedewerkers Organisatierollen
Scopes	eduv.employee.basic eduv.employee.communication eduv.employee.roles
Objecten	Employee EmployeeCommunication EmployeeRoles
Bron	Administratiesysteem onderwijsmedewerker
Afnemer	Administratiesysteem onderwijsdeelnemer Bestelomgeving leermiddelen Dienst met SSO Authenticerende Dienst Authenticerende Identity Provider Delegerende Identity Provider
Endpoints	Administratiesysteem onderwijsmedewerker POST Search Employee GET Employees 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: Employee (Onderwijsmedewerker)

Het object Employee beschrijft de identifiers, de namen van de onderwijsmedewerker en overige kenmerken. Dit object is beschikbaar vanuit de scope employee.basic.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
userMasterIdentifier	string	string	De primaire identifier voor de onderwijsmedewerker.		V*	De werkingsregels is dat de primaire identifier wordt gehanteerd in het object. Er is nog geen primaire identifier voor onderwijsmedewerkers. Enkel secundaire identifiers worden gehanteerd. In geval van een uitzonderingssituatie kan gebruik gemaakt van een secundaire identifier.
userIds	array	userId	Een lijst van secundaire identifiers die gehanteerd kan worden als de primaire identifier ontbreekt.	[{userId: ‘pietjepukkelen@petteflatcollege', userIdType: 'nlEduPersonRealId’}] Zie referentie naar eindgebruiker	V*	Zodra een secundaire identifier voor een uitzonderingssituatie gehanteerd wordt dan wordt naast het Id ook het Type gespecificeerd. Zie de pagina Identiteiten voor de toegestane secundaire identifiers.
givenName	string	string	De voornaam (of voornamen) van de onderwijsmedewerker		V
preferredFirstName	string	string	De roepnaam van de onderwijsmedewerker		V
familyName	string	string	De achternaam van de onderwijsmedewerker		V
familyNamePrefix	string	string	Het tussenvoegsel uit de achternaam van de onderwijsmedewerker		O
alias	string	string	Een extra kenmerk vanuit het Administratiesysteem onderwijsmedewerker om medewerkers te kunnen onderscheiden. Dit veld kan gebruikt worden bij de presentatie van een medewerker op het scherm, om medewerkers met dezelfde voor- en achternaam te onderscheiden.	kees2	O	Dit kenmerk kan in bepaalde gevallen een persoonsgegeven zijn.
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