Employees API

Titel	Employees API
Status	Final Recommended
Versie	Documentatie: 1.0.1
Versie	schemaVersion: 1.0.0
Beheer	Werkgroep Doorgifte Administratie
Ingangsdatum	September 2025

De Employees API wordt gebruikt om persoonsgegevens over onderwijsmedewerkers uit het Administratiesysteem onderwijsmedewerker te delen in het Afsprakenstelsel Edu-V. Deze API wordt aangeboden als onderdeel van de gegevensdienst Onderwijsmedewerker met het Administratiesysteem onderwijsmedewerker 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 Rollen
Scopes	eduv.employee.basic eduv.employee.communication eduv.employee.roles
Objecten	Employee EmployeeCommunication EmployeeRoles OrganisationRoles
Bron	Administratiesysteem onderwijsmedewerker
Afnemer	employee.basic en employee.communication Administratiesysteem onderwijsdeelnemer Bestelomgeving leermiddelen Dienst met SSO Authenticerende Dienst Authenticerende Identity Provider Delegerende Identity Provider employee.roles Nog geen afnemers
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. In geval van een uitzonderingssituatie kan gebruik gemaakt van een secundaire identifier. Er is nog geen primaire identifier voor onderwijsmedewerkers. Enkel secundaire identifiers worden gehanteerd.
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. Dit kenmerk kan in bepaalde gevallen een persoonsgegeven zijn.	kees2	O
status	string	ENUM	De status van dit object. De status geeft aan of het object al dan niet verwijderd kan worden.	active tobedeleted	V
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