Page Comparison

openapi: 3.0.0
info:
  title: Employees API
  version: '0.09.21'
  description: |-
    The Employees API is implemented by the `Administratiesysteem onderwijsmedewerker`.
    
    Employee data is split into the following objects with corresponding attributes:
    - Basic data: identifiers and name
    - Communication: email, phone, and mobile
    - Roles: organisation roles of the employee within the school
    
    Not all Employee attributes are available to all consuming reference components.
    All objects have a different security scope which allows the `Administratiesysteem onderwijsmedewerker` to share the attributes only with the reference components that are allowed to receive the attributes.
    
    All consunming reference components require consent to request data from the Employees API.
    The Notifications API can be used by consuming reference components to receive notifications about new, modified, or deleted entitities within the Employees API.

    The Employees API has a scope of primary and secundarysecondary education. Vocational education is out of scope. For Vocational Education we advice to use the [Open Education API (OOAPI)](https://openonderwijsapi.nl/).
  contact:
    name: Edu-V
    url: www.edu-v.org/afsprakenstelsel
    email: info@edu-v.org
components:
  schemas:
  
    schemaVersion:
      type: string
      description: ' |
        Schema version of this event/objectAPI using semantic versioning 2.0.0'.
      default: 0.0.2 The API version number is communicated in the header.
      Employee:  The major version is communicated in title:the EmployeeURI.
      description: 'The EmployeeFor objectmore withinformation itssee identifiers and name information.'the [Edu-V versioning guidelines](https://edu-v.atlassian.net/wiki/spaces/AFSPRAKENS/pages/9437200/Versiebeheer).
      typedefault: object
0.9.1
     x-tags:     
   - Employee:
      propertiestitle: Employee
      description: userMasterIdentifier:|
        The Employee type:object stringwith its identifiers and name information.

    description: |   Based on the scopes additional attributes can be included in Thethis primaryobject.
identifier
for the Employee.      ### employee.communication
     For Employees this valueCommunication isdata empty.of Therethe isEmployee. noFor primaryEmployees identifierthis foris Employees.the `e-mail` address, `phone` number or `mobile` phone number userIds:as provided by the School.

     type: array  ### employee.roles
       description: |`organisationRoles` of the Employee within the school.
      Atype: secundaryobject
identifier for the Employee. This value isx-tags:
used whenever the primary identifier is not available. - Employee
      properties:
   For Employees this value is mandatory.userMasterIdentifier:
          itemstype: string
           typedescription: object|
            properties:The primary identifier for the Employee.
         userId:   For Employees this value is empty. There is no primary identifier for Employees.
 type: string      userIds:
        userIdType:  type: array
             typedescription: string|
            A secondary identifier for enum:a User. This value is used whenever the primary identifier is not available.
      - nlPersonProfileId     For Employees this value is mandatory.
        - nlPersonRealId   (either userMasterIdentifier or userIds is required)
          -items:
Las-key            type: object
     - BasispoortId      properties:
      required:        userId:
      - userId         type: string
    - userIdType         schemaVersionuserIdType:
          $ref: '#/components/schemas/schemaVersion'     type: string
     givenName:           typeenum:
string         familyName:         - NEPPI type:# stringnlPersonProfileId – value can be used for students and familyNamePrefix:employees
          type: string       - BPI sourcedId:# Basispoort ID – value can be used for students and type:employees
string           format: uuid      - eduID # eduID identifier description:– |value can be used for students and employees
     The Source Identifier of the object. This is a GUID System ID for an- object.eckId # ECK iD – value can be used for employees only,  ThiseckId is theuserIdType GUIDfor thatuserMasterIdentifier Consumersfor willstudents
refer to when making API calls, or when needing to identify an object.            required:
              - userId
   It is RECOMMENDED that systems are able to map whichever local ids (e.g. database key fields), userMasterIdentifier or userIds they use to SourceId.- userIdType
        givenName:
          type: string
 The sourcedId of an object is considered anpreferredFirstName:
addressable property of an entity and as such will not betype: treatedstring
as Personally Identifiable Information (PII).    familyName:
          type: string
        familyNamePrefix:
The sourceId attribute is based on the [Base Class from OneRoster](https://www.imsglobal.org/sites/default/files/spec/oneroster/v1p2/rostering-informationmodel/OneRosterv1p2RosteringService_InfoModelv1p0.html#Data_Base).type: string
        statusemail:
          descriptiontype: | string
          description: 'E-mail address hosted by school  The status field gives an indication to Consumers about the status of an object.(e.g. L123456@school.nl).'
        phone:
          type: string
    Consumers can delete objects that are flaggeddescription: `tobedeleted`'Phone number as suchprovided ifby theythe wishschool.'
        mobile:
    The status attribute is based on the [Base Class from OneRoster](https://www.imsglobal.org/sites/default/files/spec/oneroster/v1p2/rostering-informationmodel/OneRosterv1p2RosteringService_InfoModelv1p0.html#Data_Base).
          type: string type: string
          description: 'Mobile phone number as provided by the school.'
        organisationRoles:
     enum:     type: array
      - active   description: 'The organisation roles the Employee has within the organisation.'
- tobedeleted         dateCreateditems:
            type: stringobject
            descriptionproperties:
'Indicates the date and time the object was first created. Format: Conform openapi in ZULUorganisation:
time zoals gespecificeerd in RFC 3339, section 5.6.'           format$ref: date-time'#/components/schemas/SchoolReference'
          example: "2017-07-21T17:32:28Z"   organisationRole:
     dateLastModified:           type: string
                description: 'IndicatesThe organisation role the dateEmployee andhas timewithin the object was last modified. Format: Conform openapi in ZULU time zoals gespecificeerd in RFC 3339, section 5.6.'organisation.'
                enum:
      format: date-time           example:- "2022-08-11T15:31:12Z"administratief-medewerker
      required:            - userIdsapplicatiebeheerder
        - schemaVersion         - givenNamebegeleider
        - familyName         - invalkracht
status         - sourceId        - ibp-er
dateCreated         - dateLastModified        - leermiddelencoordinator
EmployeeCommunication:       title: EmployeeCommunication       description: 'Communication data of- theleraar
Employee. For Employees this is the e-mail address, phone number or mobile phone number as provided by the School.'- mentor
     type: object       x-tags:     - onderwijsbestuurder
  - EmployeeCommunication       properties:        - sourceId:onderwijsdirecteur
          type: string       - stagiair
  format: uuid           descriptionbeginDate:
  'The Source Identifier of the Employee.'         schemaVersion:type: string
               $ref description: '#/components/schemas/schemaVersion'
        email:
   The start date on which the role becomes active (inclusive). Format: YYYY-MM-DD (according to RFC3339).'
      type: string         format: date
description: 'E-mail address hosted by school (e.g. L123456@school.nl).'         phoneexample: '2022-07-31'
         type: string    endDate:
      description: 'Phone number as provided by the school.'   type: string
     mobile:           typedescription: string'The end date on which the role becomes inactive   description: 'Mobile phone number as provided by the school(exclusive). Format: YYYY-MM-DD (according to RFC3339).'
      required:         - sourceIdformat: date
       - schemaVersion        example: '2024-08-31'
email      EmployeeRoles:      required:
title: EmployeeRoles       description: 'Roles of the Employee within the- school.'organisation
      type: object       x-tags: organisationRoles
       - EmployeeRoles      - properties:beginDate
        sourceId:
          type: string
          format: uuid
          description: 'The|
Source Identifier of the Employee.'        The schemaVersion:Source Identifier of the object. This is a GUID System ID $ref: '#/components/schemas/schemaVersion'
for an object.
       organisationRoles:     This is the GUID that Consumers type:will arrayrefer to when making API calls, or when needing to identify description: 'The organisation roles the Employee has within the organisation.'an object.
            It is RECOMMENDED that systems are items:able to map whichever local ids (e.g. database key fields), userMasterIdentifier or userIds type:they objectuse to SourceId.
          properties:  The sourcedId of an object is considered an addressable property of an entity organisation:and as such will not be treated as Personally Identifiable Information (PII).
     $ref: '#/components/schemas/SchoolReference'      
        organisationRole:    The sourceId attribute is based on the [Base Class from OneRoster](https://www.imsglobal.org/sites/default/files/spec/oneroster/v1p2/rostering-informationmodel/OneRosterv1p2RosteringService_InfoModelv1p0.html#Data_Base).
  type: string     status:
           description: 'The organisation role the Employee has within the organisation.'|
            The status field gives an indication to Consumers about enum:the status of an object.
            Consumers can -delete administratief-medewerkerobjects that are flagged `tobedeleted`  as such if they wish.

       - applicatiebeheerder    The status attribute is based on the [Base Class from OneRoster](https://www.imsglobal.org/sites/default/files/spec/oneroster/v1p2/rostering-informationmodel/OneRosterv1p2RosteringService_InfoModelv1p0.html#Data_Base).
    - begeleider     type: string
          enum:
 - invalkracht          - active
       - ibp-er    - tobedeleted
        dateCreated:
    - leermiddelencoordinator     type: string
          description: 'Indicates -the leraardate and time the object was first created. Format: Conform openapi in ZULU time zoals gespecificeerd in RFC 3339, - mentorsection 5.6.'
          format: date-time
      - onderwijsbestuurder   example: "2017-07-21T17:32:28Z"
        dateLastModified:
     - onderwijsdirecteur    type: string
          description: 'Indicates the -date stagiairand time the object was last modified. Format: Conform openapi in ZULU time zoals gespecificeerd beginDate:in RFC 3339, section 5.6.'
          format: date-time
type: string         example: "2022-08-11T15:31:12Z"
      descriptionrequired:
 'The start date on which the role becomes- activeuserIds
(inclusive). Format: YYYY-MM-DD (according to RFC3339).'   - givenName
        - familyName
  format: date     - status
        - sourceId
example: '2022-07-31'       - dateCreated
      endDate:  - dateLastModified

    # This UserReference might not be necessary for type:the stringEmployees API. References are made based on the sourceId of the Employee object.
    descriptionUserReference:
'The end date on which the roletype: becomesobject
inactive (exclusive). Format: YYYY-MM-DD (according to RFC3339).'
 title: UserReference
      properties:
        formatuserMasterIdentifier:
date          type: string
     example: '2024-08-31'    description: |
       required:     The primary identifier for a User.
    - organisation       For Students the ECK iD is used.
 - organisationRoles          For Employees this value is -empty. beginDateThere is no primary identifier for Employees.
required:         - sourceId  (either userMasterIdentifier or userIds is required)
 - schemaVersion      userIds:
  - organisationRoles      # Thistype: UserReferencearray
might not be necessary for the Employees API. References are madedescription: based|
on the sourceId of the Employee object.     UserReference: A secondary identifier for a User. type:This objectvalue is used whenever the primary identifier title:is UserReferencenot available.
     properties:       For Employees userMasterIdentifier:this value is mandatory.
       type: string    (either userMasterIdentifier or userIds is required)
 description: |        items:
    The primary identifier for a User.   type: object
        For Employees this value isproperties:
empty. There is no primary identifier for Employees.       userId:
     (either userMasterIdentifier or userIds is required)      type: string
 userIds:           type: array userIdType:
         description: |      type: string
     A secundary identifier for a User. This value is used whenever theenum:
primary identifier is not available.             For Employees- thisNEPPI value# isnlPersonProfileId mandatory.– value can be used for students and employees
    (either userMasterIdentifier or userIds is required)         - BPI items:# Basispoort ID – value can be used for students and employees
 type: object             properties:   - eduID # eduID identifier – value can be used for students userId:and employees
               type: string  - NEPRI # nlPersonRealId – value can be used for students only
 userIdType:                 type:- stringASI # Las-key – value can be used for students only
      enum:            - eckId # ECK iD – value -can nlPersonProfileIdbe used for employees only, eckId is userIdType for userMasterIdentifier for students
       - nlPersonRealId    required:
              - Las-keyuserId
              - userIdType
  - BasispoortId   required:
        - userIds
    
- Medewerkernummer   SchoolReference:
      type: object
 required:     title: SchoolReference
      description: 'A -reference userIdto a School organisation.'
      properties:
    - userIdType   organisationMasterIdentifier:
      SchoolReference:
      type: object
      title: SchoolReference
      description: 'A reference to a School organisation'
      properties:
        organisationMasterIdentifier:
          type: string
          description: |
            The primary identifier for a School. For Schools the `Onderwijsaanbiedercode``OnderwijsaanbiederId` is used.
            (either organisationMasterIdentifier or organisationIds is required)
          example: '104A158' # De Mariënborn
        organisationIds:
          type: array
          description: |
            A secundarysecondary identifier for the School. This value is used whenever the primary identifier is not available.
            (either organisationMasterIdentifier or organisationIds is required)
          items:
            type: object
            properties:
              organisationId:
                type: string
              organisationIdType:
                type: string
                enum:
                  - InstellingserkenningOIE_CODE # Onderwijsinstellingserkenningcode e.g. 09QQ (Marienbornschool)
                  - VestigingserkenningBP_ID # e.g. 09QQ00 (Marienbornschool)Basispoort gegenereerde identifier voor de school.
                  - BasispoortIdDD_ID # Door Basispoortde gegenereerdeCentrale identifierRegistratie voor de school.
                  - DigiDeliveryId # Door de Centrale Registratie van van Edu-iX gegenereerde identifierDigiDeliveryId van de school.
                  - LAS-keyAS_ID # Door het Leerlingadministratiesysteem gegenereerde identifier van de school.
            required:
              - organisationId
              - organisationIdType

    StatusResponse:
      title: StatusResponse
      type: object
      description: 'Functional status code and status message.'
      properties:
        status:
          type: integer
          description: 'See functional status codes within the Documentation.'
        statusMessage:
          type: string
          description: 'See functional status messages within the Documentation.'
      required:
        - status
  
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.example.com/oauth2/token
          refreshUrl: https://api.example.com/oauth2/token
          scopes:
            eduv.employee.basic: 'a scope that gives access to employee identifersidentifiers and name.'
            eduv.employee.communication: 'a scope that gives access to employee communication attributes.'
            eduv.employee.roles: 'a scope that gives access to employee organisation roles attributes.'
            
paths:
  
  /employees/:
    parameterspost:
      - schemasummary: Search Employee
      x-tags:
  type: string     - Employee
  name: edu_org_id   tags:
     in: query  - Administratiesysteem onderwijsmedewerker
    required: true operationId: search-employee
      description: |'Request an Employee object for a specified Employee at a School.'
All data from the Employees API requiresrequestBody:
a consent from the School.    content:
      The `edu_org_id` parameter is mandatoryapplication/json:
to request information from the `Administratiesysteem onderwijsmedewerker`.      schema:
    This allows the `Administratiesysteem onderwijsmedewerker` to check if the requesting client has an active data exchange (consent) for the specified edu_org_id.type: object
             - schemaproperties:
          type: string         nameschool:
sourceId         in: query         required$ref: true'#/components/schemas/SchoolReference'
        description: 'Reference to the sourceId of the Employee object.'employee:
      - schema:           type$ref: string'#/components/schemas/UserReference'
        name: schemaVersion     required:
   in:  query         required: false - school
      description: 'Optional parameter to request a response in a specific schema- version.employee
If none supplied, the server will chooseresponses:
its default schema version.'     get'200':
      summary: 'Get Employee'  description: OK
   x-tags:       content:
 - Employee       tags:   application/json:
     - Administratiesysteem onderwijsmedewerker       operationIdschema:
get-employee        description: |       type: array
Request an Employee object based on its sourceId.         Theitems:
Source Identifier is the GUID System ID for an object. This is the GUID that Consumers will refer to when making API calls.
        The sourcedId of an object is considered an addressable property of an entity and as such will not be treated as Personally Identifiable Information (PII).
      responses:
        '200$ref: '#/components/schemas/Employee'
        '400':
          description: OKBad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeStatusResponse'
        '400401':
          description: Bad RequestUnauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401403':
          description: UnauthorizedForbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '403404':
          description: Not ForbiddenFound
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
      security:
        - '404'OAuth2:
           description: Not Found- eduv.employee.basic
          content:  - eduv.employee.communication
         application/json:   - eduv.employee.roles

  /employees/{sourceId}:
    parameters:
 schema:     - schema:
          $reftype: '#/components/schemas/StatusResponse'string
        securityname: sourceId
       - OAuth2in: path
        required: true
 -   employee.basic    /employees/school/description: 'Reference to the  parameters:sourceId of the Employee object.'
      - schema:
          type: string
        name: edu_org_idorgMasterId
        in: query
        required: truefalse
        description: |
          AllThe dataorganisationMasterIdentifier fromof the Employeesschool.
API requires a consent from the School.    This parameter is used when the primary The `edu_org_id` parameter is mandatory to request information from the `Administratiesysteem onderwijsmedewerker`identifier for a school (being the `OnderwijsaanbiederId`) is available.
      - schema:
  This allows the `Administratiesysteem onderwijsmedewerker` to check if thetype: requestingstring
client has an active data exchange (consent) for thename: specified edu_org_id.orgId
       - schemain: query
         $refrequired: '#/components/schemas/SchoolReference'false
        namedescription: school|
        in: query
     The organisationIdentifier (secondary identifier) of the school.
    required: true     This parameter is used description:in 'Referencecombination towith the primaryorgIdType orwhen secundarythe identifierorganisationMasterIdentifier ofis anot schoolavailable.'
      - schema:
          type: integerstring
        name: start example: DD_ID
      in: query   enum:
     description: 'Start point for pagination of results, defaults- to 0,'OIE_CODE
         examples:   - BP_ID
      default:      - DD_ID
     value: 0      - AS_ID
     summary: The start pointname: fororgIdType
pagination       - schemain: query
         typerequired: integerfalse
          maximumdescription: 100|
        name: limit The type of the organisationIdentifier.
   in: query      This parameter is description:used 'Limitin ofcombination numberwith ofthe resultsorgId returnedwhen bythe page,organisationMasterIdentifier defaultsis tonot 20available.
with max 100.'  get:
      examplessummary: 'Get Employee'
        defaultx-tags:
        - Employee
  value: 20   tags:
        - summary:Administratiesysteem Theonderwijsmedewerker
default value if none is provided operationId: get-employee
      description: |
max:        Request an Employee object based value:on 100its sourceId.
        The Source Identifier summary:is The largest recommended page size
      - schema:
   the GUID System ID for an object. This is the GUID that Consumers will refer to when making API calls.
      type: string The sourcedId of an object is considered an addressable property format: date-time
        in: query
 of an entity and as such will not be treated as Personally Identifiable Information (PII).
      nameresponses:
since        '200':
required: false         description: OK
'Request   all objects modified after the specified timestamp. Formatcontent:
Conform openapi in ZULU time as specified in RFC 3339, section 5.6'
 application/json:
       example: "2017-07-21T17:32:28Z"       - schema:
          type: string     $ref: '#/components/schemas/Employee'
  name: schemaVersion     '400':
   in: query      description: Bad Request
required: false         descriptioncontent:
 'Optional parameter to request a response in a specific schema version. If none supplied, the server will choose its default schema version.' application/json:
              getschema:
      summary: Get Employees for School       x-tags:$ref: '#/components/schemas/StatusResponse'
        -'401':
Employee       tags:   description: Unauthorized
    - Administratiesysteem onderwijsmedewerker    content:
  operationId: get-employees-for-school       description: 'Request all Employee objects including basic information (identifiers and names) for a specified school.' application/json:
                 responsesschema:
        '200':           description$ref: OK'#/components/schemas/StatusResponse'
          content'403':
            application/jsondescription: Forbidden
             schemacontent:
                typeapplication/json:
array                 items:
 schema:
                $ref: '#/components/schemas/EmployeeStatusResponse'
        '400404':
          description: BadNot RequestFound
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401'security:
        -  descriptionOAuth2:
Unauthorized           content: -  eduv.employee.basic
         application/json:      - eduv.employee.communication
        schema:    - eduv.employee.roles
  
  /employees/school:
     $refparameters:
'#/components/schemas/StatusResponse'      -   '403'schema:
          descriptiontype: Forbiddenstring
        name: orgMasterId
content:        in: query
   application/json:     required: false
        schemadescription: |
          The organisationMasterIdentifier of the school.
$ref: '#/components/schemas/StatusResponse'         '404':This parameter is used when the primary identifier for a school description:(being Notthe Found`OnderwijsaanbiederId`) is available.
      -  contentschema:
          type: string
   application/json:     name: orgId
        schemain: query
        required: false
        $refdescription: '#/components/schemas/StatusResponse'|
        security:  The organisationIdentifier (secondary identifier) of the school.
- OAuth2:         This parameter is used -in employee.basiccombination with the  /employees/communication/:
    parameters:orgIdType when the organisationMasterIdentifier is not available.
      - schema:
          type: string
          nameexample: edu_org_idDD_ID
          inenum:
query         required: true  - OIE_CODE
     description: |      - BP_ID
   All data from the Employees API requires a consent from the School.- DD_ID
            The- `eduAS_org_id`ID
parameter is mandatory to request information from the `Administratiesysteemname: onderwijsmedewerker`.orgIdType
        in: query
This allows the `Administratiesysteem onderwijsmedewerker` to check if therequired: requestingfalse
client has an active data exchange (consent) for thedescription: specified edu_org_id.|
       - schema:  The type of the organisationIdentifier.
    type: string     This parameter is used name:in sourceIdcombination with the orgId when the organisationMasterIdentifier is not in:available.
query      - schema:
 required: true         descriptiontype: 'Referencestring
to the sourceId of the Employee object.'    format:   date-time
schema:           typein: stringquery
        name: schemaVersionsince
        inrequired: queryfalse
        requireddescription: false'Request all objects modified after the specified timestamp. Format: description:Conform 'Optionalopenapi parameterin toZULU requesttime aas responsespecified in aRFC specific3339, schemasection version5.6'
If none supplied, the server will choose its default schema version.'example: "2017-07-21T17:32:28Z"
    get:
      summary: 'Get Employees Employeefor Communication'School
      x-tags:
        - EmployeeCommunicationEmployee
      tags:
        - Administratiesysteem onderwijsmedewerker
      operationId: get-employeeemployees-for-communicationschool
      description: |'Request all Employee objects including basic information (identifiers and Requestnames) thefor communicationa attributesspecified ofschool.'
Employee object based on its sourceId. responses:
       The Source'200':
Identifier is the GUID System ID for an object. This isdescription: theOK
GUID that Consumers will refer to when making API calls.  content:
      The sourcedId of an object is consideredapplication/json:
an addressable property of an entity and as such will not be treated as Personallyschema:
Identifiable Information (PII).       responses:       type: array
'200':           description: OK    items:
      content:            $ref: application/json:
              schema:
                $ref: '#/'#/components/schemas/EmployeeCommunicationEmployee'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
      security:
        - OAuth2:
            - eduv.employee.communication

  /employees/communication/school/:basic
     parameters:       - schema:eduv.employee.communication
          type: string - eduv.employee.roles

x-tags:
  -  name: edu_org_idEmployee
        in- name: queryEmployeeCommunication
        required: true
        description: |
          All data from the Employees API requires a consent from the School.
          The `edu_org_id` parameter is mandatory to request information from the `Administratiesysteem onderwijsmedewerker`.
          This allows the `Administratiesysteem onderwijsmedewerker` to check if the requesting client has an active data exchange (consent) for the specified edu_org_id.
      - schema:
          $ref: '#/components/schemas/SchoolReference'
        name: school
        in: query
        required: true
        description: 'Reference to the primary or secundary identifier of a school.'
      - schema:
          type: integer
        name: start
        in: query
        description: 'Start point for pagination of results, defaults to 0,'
        examples:
          default:
            value: 0
            summary: The start point for pagination
      - schema:
          type: integer
          maximum: 100
        name: limit
        in: query
        description: 'Limit of number of results returned by page, defaults to 20 with max 100.'
        examples:
          default:
            value: 20
            summary: The default value if none is provided
          max:
            value: 100
            summary: The largest recommended page size
      - schema:
          type: string
          format: date-time
        in: query
        name: since
        required: false
        description: 'Request all objects modified after the specified timestamp. Format: Conform openapi in ZULU time as specified in RFC 3339, section 5.6'
        example: "2017-07-21T17:32:28Z"
      - schema:
          type: string
        name: schemaVersion
        in: query
        required: false
        description: 'Optional parameter to request a response in a specific schema version. If none supplied, the server will choose its default schema version.'
    get:
      summary: Get Employees Communication for School
      x-tags:
        - EmployeeCommunication
      tags:
        - Administratiesysteem onderwijsmedewerker
      operationId: get-employees-communication-for-school
      description: 'Request communication attributes for all Employee objects for a specified school.'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EmployeeCommunication'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
      security:
        - OAuth2:
            - employee.communication

  /employees/roles/:
    parameters:
      - schema:
          type: string
        name: edu_org_id
        in: query
        required: true
        description: |
          All data from the Employees API requires a consent from the School.
          The `edu_org_id` parameter is mandatory to request information from the `Administratiesysteem onderwijsmedewerker`.
          This allows the `Administratiesysteem onderwijsmedewerker` to check if the requesting client has an active data exchange (consent) for the specified edu_org_id.
      - schema:
          type: string
        name: sourceId
        in: query
        required: true
        description: 'Reference to the sourceId of the Employee object.'
      - schema:
          $ref: '#/components/schemas/SchoolReference'
        name: school
        in: query
        required: false
        description: 'Optional filter to request the organsiation roles of the Employee at the specified school. Reference to the primary or secundary identifier of a school.'
      - schema:
          type: string
        name: schemaVersion
        in: query
        required: false
        description: 'Optional parameter to request a response in a specific schema version. If none supplied, the server will choose its default schema version.'
    get:
      summary: 'Get Employee Roles'
      x-tags:
        - EmployeeRoles
      tags:
        - Administratiesysteem onderwijsmedewerker
      operationId: get-employee-roles
      description: |
        Request the organiation roles attributes of Employee object based on its sourceId.
        The Source Identifier is the GUID System ID for an object. This is the GUID that Consumers will refer to when making API calls.
        The sourcedId of an object is considered an addressable property of an entity and as such will not be treated as Personally Identifiable Information (PII).
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeRoles'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
      security:
        - OAuth2:
            - employee.roles

  /employees/roles/school/:
    parameters:
      - schema:
          type: string
        name: edu_org_id
        in: query
        required: true
        description: |
          All data from the Employees API requires a consent from the School.
          The `edu_org_id` parameter is mandatory to request information from the `Administratiesysteem onderwijsmedewerker`.
          This allows the `Administratiesysteem onderwijsmedewerker` to check if the requesting client has an active data exchange (consent) for the specified edu_org_id.
      - schema:
          $ref: '#/components/schemas/SchoolReference'
        name: school
        in: query
        required: true
        description: 'Reference to the primary or secundary identifier of a school.'
      - schema:
          type: integer
        name: start
        in: query
        description: 'Start point for pagination of results, defaults to 0,'
        examples:
          default:
            value: 0
            summary: The start point for pagination
      - schema:
          type: integer
          maximum: 100
        name: limit
        in: query
        description: 'Limit of number of results returned by page, defaults to 20 with max 100.'
        examples:
          default:
            value: 20
            summary: The default value if none is provided
          max:
            value: 100
            summary: The largest recommended page size
      - schema:
          type: string
          format: date-time
        in: query
        name: since
        required: false
        description: 'Request all objects modified after the specified timestamp. Format: Conform openapi in ZULU time as specified in RFC 3339, section 5.6'
        example: "2017-07-21T17:32:28Z"
      - schema:
          type: string
        name: schemaVersion
        in: query
        required: false
        description: 'Optional parameter to request a response in a specific schema version. If none supplied, the server will choose its default schema version.'
    get:
      summary: Get Employees Roles for School
      x-tags:
        - EmployeeRoles
      tags:
        - Administratiesysteem onderwijsmedewerker
      operationId: get-employees-roles-for-school
      description: 'Request organisation roles attributes for all Employee objects for a specified school.'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EmployeeRoles'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
      security:
        - OAuth2:
            - employee.roles

x-tags:
  - name: Employee
  - name: EmployeeCommunication
  - name: EmployeeRoles