get:
  tags:
    - Patient
  summary: Get per-patient funduscopy status for one care group
  description: |-
    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', '']
    - $ref: '../zoo-api.yaml#/components/parameters/Pretty'
    - $ref: '../zoo-api.yaml#/components/parameters/RefDateDefaultToday'
    - $ref: '../zoo-api.yaml#/components/parameters/CareGroup'
    - $ref: '../zoo-api.yaml#/components/parameters/Authorization'
  responses:
    '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.
                type: integer
                format: int32
                minimum: 1
                maximum: 99999999
              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 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.