get:
  operationId: patientFundusByGroup
  tags:
    - Patient
  summary:  Funduscopy, care group
  description: |-
    Get per-patient funduscopy status for one care group.

    Returns patients that have an indication for requiring funduscopy across all practices of a care group, taking into account
    the medical dossier of each patient as well as the care group's policies.
    
    For each patient, information about their funduscopy status as well as basic personal information is provided.
    
    This endpoint may take quite a while to respond (may take more than 5 minutes) which can cause issues with timeouts; configure your
    endpoint call function appropriately and ensure intermediate proxies don't time out either.
    
    Due to the potentially large amount of data, this endpoint rejects requests that don't support compression. A header of at least
    `Accept-Encoding: gzip` is therefore required.
  parameters:
    - $ref: '../zoo-api.yaml#/components/parameters/AgbCareGroup'
    - name: purpose
      in: query
      required: true
      description: |-
        A key describing the purpose of requesting funduscopy status of many patients.
        
        Affects what data is supplied (for example, whether personally identifying information is provided), and whether certain
        filters are applied.
        
        * `fundus-broker` – An entity that takes care of arranging appointments between patients and funduscopy professionals.
        * `gp` – Medical personnel reviewing their funduscopy-relevant patient population.
        * `reporting` – Reporting on the status of the funduscopy-relevant patient population as a whole.
        
        The `reporting` purpose limits PII, the `fundus-broker` purpose applies filtering as per the preferences of the care group's policies.
      schema:
        type: string
        enum: ['fundus-broker', 'gp', 'reporting']
    - name: director
      in: query
      required: false
      description: |-
        If present, filter the returned population on the registered director for funduscopy.
        
        * `gp` – Returns only those patients whose most recent registration of responsible-for-funduscopy is 'The GP'.
        * `specialist` – Returns only those patients whose most recent registration of responsible-for-funduscopy is 'The specialist'.
        * `unknown` – Returns only those patients whose most recent registration of responsible-for-funduscopy is not present, registered as 'Unknown', or has an invalid registration.
        
        If not present, no filtering is applied.
      schema:
        type: string
        enum: ['gp', 'specialist', 'unknown', '']
    - name: ifNewerThan
      in: query
      required: false
      description: |-
        Useful to check if new data is available relative to an earlier request: Provide the same date as provided in a previous response's `refDate` value.
        If no new data is available since then, a `206 - No Content` HTTP response is returned. Date without time part in ISO8601 format.
      schema:
        type: string
        format: date
        example: "1970-01-13"
    - $ref: '../zoo-api.yaml#/components/parameters/Pretty'
    - $ref: '../zoo-api.yaml#/components/parameters/CareGroup'
    - $ref: '../zoo-api.yaml#/components/parameters/Authorization'
  responses:
    '206':
      description: |-
        No new data is available: No new group report has been constructed with a `refDate` newer than `ifNewerThan`.
    '503':
      description: The data cannot be provided, because EPD data has not been provided to Zorg op Orde, or ZOO has not had a chance to run the fundus calculations on this data.
      content:
        application/json:
          schema:
            type: object
            required:
              - agb
              - regionName
            properties:
              agb:
                description: |-
                  The same AGB as supplied via authentication or the `agb` parameter: The AGB of the care group being queried.
                $ref: ../schemas/agb.yaml
              regionName:
                description: |-
                  A human readable name describing the care group being queried (The entity whose AGB code is sent as `agb`).
                type: string
    '200':
      description: All patients where funduscopy status is relevant are returned.
      content:
        application/json:
          schema:
            type: object
            required:
              - agb
              - regionName
              - refDate
              - practices
            properties:
              dict:
                $ref: '../schemas/TermsDictionary.yaml'
              agb:
                description: |-
                  The same AGB as supplied via authentication or the `agb` parameter: The AGB of the care group being queried.
                $ref: ../schemas/agb.yaml
              regionName:
                description: |-
                  A human readable name describing the care group being queried (The entity whose AGB code is sent as `agb`).
                type: string
              refDate:
                $ref: ../schemas/date.yaml
                example: '2024-04-01'
                description: |-
                  The date when this report for the 
                  The date used for all calculations: Any time spans are relative to this date, any measurement requirements
                  as stated in the care group's policies such as 'must be registered every year or cannot be considered' are applied
                  to this date, anything that occured after this date is ignored.
              practices:
                description: |-
                  One entry for each practice that is part of this care group and participates in at least one funduscopy-related care program.
                type: array
                items:
                  $ref: "../schemas/fundus-status.yaml"
    '400':
      description: The request is invalid; for example, it doesn't contain the required `agb` parameter.
    '401':
      $ref: '../zoo-api.yaml#/components/responses/JwtFailure'
    '403':
      description: Indicated group is known but has not authorized ZOO to share this information with signer.