openapi: 3.1.0
info:
  title: Zorg op Orde API
  description: |-
    This documentation is also available in <a href="/zoo-api-bundle.yaml">OpenAPI 3.1.0 yaml format</a>. 

    Copyright by Zorg op Orde, all rights reserved. 
  contact:
    name: Zorg op Orde
    email: api@zorgoporde.nl
  version: v0.9
servers:
  - url: https://tools.zorgoporde.nl/api1
    description: Production
  - url: https://acc.zorgoporde.nl/api1
    description: Testing
security:
  - BearerAuth: []
tags:
  - name: Patient
    description: API for retrieving medical dossier data and concerns based on looking up a specific patient.
  - name: Population statistics
    description: Statistics of a patient population.
  - name: Frequent users
    description: Gives insight and enumerates the patients who make most use of the practice. Use is defined as time needed from the doctor(s). Certain feat codes need more or less a constant time. These are used to get an approximation.
  - name: Quality of Care
    description: |-
      API related to Quality of Care (QoC) features

      A care program (dutch: _ketenzorg_ or _zorgprogramma_) describes a specific disease (such as Diabetes or Astma) or a more abstract concern such as elderly care or general concern about cardiovascular health. The same care program can show up multiple times, as there are different care programs and standards for the same disease or concern. For example, there could be the InEen report 'take' on how one should provide Diabetes care, and there could be some regional group's slightly different take on it; these would show up as different care programs.

      Any given customer has a 'fave' status for any given care program; some care programs are enabled by default and some are disabled by default. However, a customer can explicitly select a program they wouldn't ordinarily see ('favourite' it), or explicitly deselect a program they get by default ('unfavourite' it). Most care programs will be neither favourited nor unfavourited: They should be shown based on their `defaultShow` property.

      To allow favouriting/unfavouriting, the front end has 2 separate views for selecting care programs: The usual view, which shows _only_:
      - Care programs that customer has explicitly favourited.
      - Care programs that are shown by default to this customer which they did not explicitly unfavourite.

      As well as a 'config' view where they see _all_ care programs that could possibly be relevant for that customer, where the customer can preview the report (essentially, run the report as normal), favourite something they don't get by default, or unfavourite something they get by default.
  - name: Customer management
  - name: GPIS exports
    description: List and download exported parts of GPIS dossiers.
paths:
  /patient/dossier:
    get:
      operationId: patientDossier
      tags:
        - Patient
      summary: Detailed medical dossier
      description: |-
        Get detailed medical dossier info for the stated patient.

        WorkInProgress: The API may require you to provide the person on whose authority this request is being made,
        which will be logged and reviewed for the _Principle of Least Privilege_ policy.

        Known design parameters:
          - send along the date on which the result is based (GPIS snapshot date)
          - Sender must send a key (or list of keys) representing the context, such as 'DM', 'Obesitas', 'Dietetiek', etc. We combine the targeted data (the GP or zorggroep) with these keys to know precisely what we filter (we do not just return all medical dossier data).
          - uptime is important; these API calls are done live as patients show.
          - q - edit it a bit, can be for example 'dm' or even 'dm/dietetiek'. Send all relevant parts in one response.
          - required response categories: Journaal, Bepalingen, Medicatie, episodes.
      parameters:
        - $ref: '#/components/parameters/AgbGP'
        - name: bsn
          in: query
          description: |-
            The SSN (dutch: _BSN_) of a patient to look up. May only contain digits, cannot contain more than 9 digits, and cannot be 0.
            Either `bsn` or `pu` must be present. Note that `bsn` can also be sent via header (not recommended).
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 999999999
            example: 123456789
        - name: bsn
          in: header
          description: An alternate location for the `bsn` parameter.
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 999999999
            example: 123456789
        - name: pu
          in: query
          required: false
          description: |-
            The Patient unique ID, as e.g. reported by `/patient/base`'s `patUnid` response.

            Either `bsn` or `pu` must be present. We do not recommend including both; if this is done, _both_ filters are applied, and
            patient info is only returned if a patient exists matching both.
          schema:
            type: string
            example: ''
        - name: q
          in: query
          required: false
          description: |-
            A comma-separated list of dossier aspects to query. If omitted, everything is returned.
            The keys match the keys in the JSON structure that is returned on a success, such as `medication` or `measurements`.

            Current list of aspects:
            - personal (basic info such as birth dates and address)
            - careprograms (which actively managed chronic care programs the patient participates in)
            - episodes (chronic conditions and problems)
            - measurements (lab values, process management, answers to basic questions)
            - feats (declared acts such as 'standard consult')
            - correspondence (messages sent and received about this patient to other care professionals)
            - medications
            - contraindications
            - journals
          schema:
            type: array
            items:
              type: string
            minItems: 1
            example: q=medication,measurements
        - name: purpose
          in: query
          description: |-
            A unique key identifying for what purpose this request is being made. Keys are agreed upon between
            ZorgOpOrde and the API user, and will result in the data returned filtered down to what is relevant / necessary for
            the stated purpose. For example, `"diet-dm2"` would be a key to represent that this patient is being
            enrolled in Diabetes Mellitus chronic care and a report on this patient's DM status is being prepared to send
            to a licensed dietitian. The data returned would be filtered to only include those aspects relevant for this task.
          required: true
          schema:
            type: string
            example: diet-dm2
        - $ref: '#/components/parameters/Authorization'
      responses:
        '200':
          description: |-
            Detailed medical dossier information for the patient is returned.

            Filtered to only return what was requested (via optional query parameter `q`), and including only those aspects
            of the medical dossier relevant for the stated purpose.
          content:
            application/json:
              schema:
                type: object
                properties:
                  personal:
                    description: Contains core identification information about this patient; a duplication of the `/patient/base` API.
                    type: object
                    required:
                      - bsn
                      - name
                      - gender
                      - patid
                      - patUnid
                      - category
                      - startDate
                    properties:
                      bsn:
                        $ref: '#/components/schemas/pat-BSN'
                      name:
                        $ref: '#/components/schemas/pat-Name'
                      gender:
                        $ref: '#/components/schemas/gender'
                      dob:
                        $ref: '#/components/schemas/date'
                      category:
                        $ref: '#/components/schemas/category'
                      doctor:
                        $ref: '#/components/schemas/doctor'
                      address:
                        $ref: '#/components/schemas/address'
                      contact:
                        $ref: '#/components/schemas/contact'
                      insurance:
                        $ref: '#/components/schemas/insurance'
                      patid:
                        $ref: '#/components/schemas/pat-patId'
                      patPubId:
                        $ref: '#/components/schemas/pat-patPubId'
                      patUnid:
                        $ref: '#/components/schemas/pat-patUnid'
                      startDate:
                        $ref: '#/components/schemas/date'
                      endDate:
                        $ref: '#/components/schemas/date'
                      endReason:
                        $ref: '#/components/schemas/endReason'
                  episodes:
                    type: array
                    description: 'Lists chronic problems or other diagnosed medical issues (dutch: _behandelingen / episodes / problemen_) based on ICPC1-NL.'
                    items:
                      $ref: '#/components/schemas/Episode'
                  measurements:
                    type: array
                    description: |-
                      Lists measurements, including lab-determined values (example: Direct measurement of LDL cholesterol in a blood sample),
                      measurements done by the practicioner or by the patient themselves (example: weight), care process information
                      (such as 'responsible for chronic diabetes care: Specialist'), and answers to questionnaires such as 'do you have trouble
                      walking up stairs').
                    items:
                      $ref: '#/components/schemas/Measurement'
                  feats:
                    type: array
                    description: |-
                      Lists declarable acts (dutch: _verrichtingen_, also known as _prestaties_), and includes:
                      * actual work done (such as spending 10 minutes with a patient)
                      * material that is paid separately (such some nitrogen to burn off a wart)
                      * 'subscription' fees such as the standard subscription fee as well as extras charged for each patient per quarter (dutch: _inschrijf_ en _module_ tarieven).
                    items:
                      $ref: '#/components/schemas/Feat'
                  correspondence:
                    type: array
                    description: Lists records of correspondence (excluding correspondence within the GP office and correspondence with the patient themselves).
                    items:
                      $ref: '#/components/schemas/Correspondence'
                  medications:
                    type: array
                    description: Lists medication, either prescribed, or delivered to the patient (or both, of course).
                    items:
                      $ref: '#/components/schemas/Medication'
                  contraindications:
                    type: array
                    description: |-
                      Lists registered contra-indications, also often used for the generalized concept of popping up warnings any time
                      this patient's information is shown to a practicioner. Generally simply is an alternate take on a list of problems
                      a patient suffers from; specifically issues that may affect unrelated care (such as allergies, mental issues, and so on).
                    items:
                      $ref: '#/components/schemas/Contraindication'
                  journals:
                    type: array
                    description: |-
                      Lists registered journal entries - text typed by practicioners for a variety of reasons, including representing what the
                      patient themselves tells the practicioner (can include verbatim copies of what the patient wrote for text-based telehealth systems),
                      as well as explaining in text the conclusions included in a lab report received via mail.
                    items:
                      $ref: '#/components/schemas/Journal'
        '400':
          $ref: '#/components/responses/ReqFailure'
        '401':
          $ref: '#/components/responses/JwtFailure'
        '403':
          description: |-
            Practice associated with the JWT is known but has not authorized ZOO to share information with signer for the provided purpose.

            This error also occurs if the provided purpose isn't a known key.
        '404':
          $ref: '#/components/responses/PatNotFound'
  /patient/base:
    get:
      operationId: patientBase
      tags:
        - Patient
      summary: Basic personal patient
      description: Get basic personal patient info not directly related to their medical dossier
      parameters:
        - $ref: '#/components/parameters/AgbGP'
        - name: bsn
          in: query
          description: 'The SSN (dutch: _BSN_) of a patient to look up. May only contain digits, cannot contain more than 9 digits, and cannot be 0.'
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 999999999
            example: 123456789
        - name: bsn
          in: header
          description: An alternate location for the `bsn` parameter.
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 999999999
            example: 123456789
        - $ref: '#/components/parameters/Authorization'
      responses:
        '200':
          description: Basic personal information for the patient is returned.
          content:
            application/json:
              schema:
                type: object
                required:
                  - bsn
                  - name
                  - gender
                  - patid
                  - patUnid
                  - category
                  - startDate
                properties:
                  bsn:
                    $ref: '#/components/schemas/pat-BSN'
                  name:
                    $ref: '#/components/schemas/pat-Name'
                  gender:
                    $ref: '#/components/schemas/gender'
                  dob:
                    $ref: '#/components/schemas/date'
                  category:
                    $ref: '#/components/schemas/category'
                  doctor:
                    $ref: '#/components/schemas/doctor'
                  address:
                    $ref: '#/components/schemas/address'
                  contact:
                    $ref: '#/components/schemas/contact'
                  insurance:
                    $ref: '#/components/schemas/insurance'
                  patid:
                    $ref: '#/components/schemas/pat-patId'
                  patPubId:
                    $ref: '#/components/schemas/pat-patPubId'
                  patUnid:
                    $ref: '#/components/schemas/pat-patUnid'
                  startDate:
                    $ref: '#/components/schemas/date'
                  endDate:
                    $ref: '#/components/schemas/date'
                  endReason:
                    $ref: '#/components/schemas/endReason'
                  careprograms:
                    $ref: '#/components/schemas/careprograms'
        '400':
          description: The request is invalid; for example, it doesn't contain the required `BSN` parameter.
        '401':
          $ref: '#/components/responses/JwtFailure'
        '403':
          description: Indicated practice is known but has not authorized ZOO to share this information with signer.
        '404':
          $ref: '#/components/responses/PatNotFound'
  /patient/contactList:
    get:
      operationId: contactList
      tags:
        - Patient
      summary: Contact list
      description: Get a contact list for printing address labels, sending e-mail and/ or calling.
      parameters:
        - name: patUnids
          in: query
          mandatory: true
          description: |-
            A comma separated list of patUnid values, as provided by other API endpoints.
            For each patUnid the contact details are in the response. If sending lots of patUnids, we suggest you call this API in a POST (which is also allowed, though the semantic intent of this method is GET: It only queries and makes no changes) to avoid HTTP limits on query length.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/pat-patUnid'
            example: 1234,5678
        - name: fields
          in: query
          mandatory: true
          description: |-
            Comma separated list of data fields that shold be returned in the response. Available options are:
            bsn         - adds CSV column/JSON key 'bsn'.
            patPubId    - adds CSV column/JSON key 'patPubId'.
            patUnid     - adds CSV column/JSON key 'patUnid'.
            gender      - adds CSV column/JSON key 'gender', with values 'O', 'M', or 'F'.
            displayName - adds CSV column/JSON key 'displayName' with the full name of the patient as one would write it on an envelope.
            fullName    - adds CSV columns 'initials', 'firstNames', 'infixOwn', 'ownLastName', 'infixPartner', 'partnerLastName', and JSON key 'name' with as value an object with those keys.
            addressLine - adds CSV column/JSON key 'addressLine'.
            postcode    - adds CSV column/JSON key 'postcode'.
            city        - adds CSV column/JSON key 'city'.
            tel         - adds CSV column/JSON key 'tel'.
            email       - adds CSV column/JSON key 'email'.
            dob         - adds CSV column/JSON key 'dob'.

            See the descriptions in the JSON output section of this documentation for the formatting of these outputs.
          example: displayName,addressLine,postcode,city
        - name: Accept
          in: header
          description: |-
            This API is capable of emitting both CSV (RFC 4180) and JSON. If a CSV response is needed, ensure mimetype `text/csv` is
            mentioned in the `Accept` header at a higher quality than `application/csv`. If no Accept header is provided, the API
            responds with JSON.
          schema:
            type: string
            enum:
              - text/csv
              - application/json
      responses:
        '200':
          description: A patient contact list for (electronic) mailing or phone contact. Per patient only requested details (via `column`) are provided. Any patient that isn't found isn't included in the output.
          headers:
            Content-Type:
              description: The actual content-type of the response.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    patUnid:
                      $ref: '#/components/schemas/pat-patUnid'
                    patPubId:
                      $ref: '#/components/schemas/pat-patPubId'
                    gender:
                      $ref: '#/components/schemas/gender'
                    displayName:
                      $ref: '#/components/schemas/displayName'
                    name:
                      $ref: '#/components/schemas/pat-Name'
                    addressLine:
                      description: The concatenation of street, housenumber and -suffix on one line.
                      type: string
                    postcode:
                      $ref: '#/components/schemas/postcode'
                    city:
                      $ref: '#/components/schemas/city'
                    tel:
                      $ref: '#/components/schemas/tel'
                    email:
                      $ref: '#/components/schemas/email'
                    bsn:
                      $ref: '#/components/schemas/pat-BSN'
                    dob:
                      $ref: '#/components/schemas/date'
            text/csv:
              schema:
                type: string
                description: An RFC4180 (with comma separator) output, with headers as requested.
        '400':
          description: The request is invalid; for example, it doesn't contain the required `patUnids` or `columns` parameter.
        '401':
          $ref: '#/components/responses/JwtFailure'
        '406':
          description: |-
            An accept header was sent, but neither `text/csv` nor `application/json` is allowed by it.
            As this endpoint can only render its data in those two content types, no response is possible.
  /patient/fundusByGroup:
    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: '#/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: '#/components/parameters/Pretty'
        - $ref: '#/components/parameters/CareGroup'
        - $ref: '#/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: '#/components/schemas/TermsDictionary'
                  agb:
                    description: 'The same AGB as supplied via authentication or the `agb` parameter: The AGB of the care group being queried.'
                    $ref: '#/components/schemas/agb'
                  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: '#/components/schemas/date'
                    example: '2024-04-01'
                    description: |-
                      All fundus calculations for each practice that is part of this group is up to date as of this date.
                      This date is appropriate to feed to `ifNewerThan` in a future call.
                  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: '#/components/schemas/fundus-status'
        '206':
          description: 'No new data is available: No new group report has been constructed with a `refDate` newer than `ifNewerThan`.'
        '400':
          description: The request is invalid; for example, it doesn't contain the required `agb` parameter.
        '401':
          $ref: '#/components/responses/JwtFailure'
        '403':
          description: Indicated group is known but has not authorized ZOO to share this information with signer.
        '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: '#/components/schemas/agb'
                  regionName:
                    description: A human readable name describing the care group being queried (The entity whose AGB code is sent as `agb`).
                    type: string
  /patient/fundusByPractice:
    get:
      operationId: patientFundusByPractice
      tags:
        - Patient
      summary: Funduscopy, practice
      description: |-
        Get per-patient funduscopy status for one GP practice.

        Returns patients that have an indication for requiring funduscopy, taking into account the medical dossier of each patient as well as the relevant care group's policies.

        For each patient, information about their funduscopy status as well as basic personal information is provided.
      parameters:
        - $ref: '#/components/parameters/AgbGP'
        - 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: '#/components/parameters/Pretty'
        - $ref: '#/components/parameters/Authorization'
      responses:
        '200':
          description: All patients where funduscopy status is relevant is returned.
          content:
            application/json:
              schema:
                type: object
                required:
                  - practice
                  - refDate
                properties:
                  dict:
                    $ref: '#/components/schemas/TermsDictionary'
                  practice:
                    $ref: '#/components/schemas/fundus-status'
        '206':
          description: 'No new data is available: The EPD has not provided new information since `ifNewerThan`, or Zorg op Orde has not had a chance to rerun the fundus calculations on newly provided EPD data.'
        '400':
          description: The request is invalid; for example, it doesn't contain the required `agb` parameter.
        '401':
          $ref: '#/components/responses/JwtFailure'
        '403':
          description: Indicated group is known but has not authorized ZOO to share this information with signer.
        '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:
                  - practice
                properties:
                  practice:
                    type: object
                    required:
                      - agb
                      - name
                      - gpis
                      - refDate
                    properties:
                      agb:
                        description: The AGB code of the GP practice whose patients are provided in this object.
                        $ref: '#/components/schemas/agb'
                      name:
                        description: A human readable name describing the GP practice (The entity whose AGB code is sent as `agb`).
                        type: string
                      gpis:
                        $ref: '#/components/schemas/GPIS'
                      refDate:
                        $ref: '#/components/schemas/date'
  /population/statistics:
    get:
      tags:
        - Population statistics
      operationId: populationStatistics
      summary: Population group-by
      description: Groups the patient population by any combination of age, preferred doctor, etc. and calculates the count of each category.
      parameters:
        - $ref: '#/components/parameters/RefDateDefaultToday'
        - name: groupByItems
          in: query
          required: true
          schema:
            type: array
            minItems: 1
            items:
              type: string
              enum:
                - age
                - preferredDoctor
                - insurer
                - gender
            description: |-
              Several items can be added to the group by using a comma separated list, e.g. `groupByItems=gender,age`.
              If an item is twice or more repeated the first occurrence is used.
        - name: insurer
          in: query
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/insurer-Uzovi'
          description: Supply zero, one or more Uzovis to limit the responses to certain insurer. Use 0 to select all patients without insurer registered. Supply the Uzovi code as an integer in a comma separated list, e.g. `insurer=101,211,3344`.
        - name: passerBy
          in: query
          required: false
          schema:
            type: boolean
          description: '`true` to include passer-by patients. This also includes Medicom''s noni patients. (Noni = niet op naam ingeschreven.) By default passer-by patients are excluded from the response.'
        - $ref: '#/components/parameters/Authorization'
      responses:
        '200':
          description: |-
            The response body is a JSON-array with for each group, defined by a sequence of `groupByItem` query parameters, an object with a count `n`. 
               * Only patients with an active registration on the reference date are included. 
               * When age is chosen as a category, only patients with a birthdate are included and therefore only known ages are included in the response. 
               * The insurer is outputted as an Uzovi (with name and concern). The most recent Uzovi table is used to convert codes to names and concerns. If an Uzovi is missing in that table it is still added to the response, but without name and/or concern. 
            The sequence of the items in the URL is the same as the sequence in the grouping of the output.
          content:
            application/json:
              schema:
                type: object
                properties:
                  cohorts:
                    type: array
                    items:
                      type: object
                      properties:
                        age:
                          type: integer
                          minimum: 0
                          format: int32
                          example: 42
                        preferredDoctor:
                          $ref: '#/components/schemas/doctor'
                        insurer:
                          type: object
                          properties:
                            uzovi:
                              $ref: '#/components/schemas/insurer-Uzovi'
                            name:
                              type: string
                              description: The name of the insurer according the [Vektis register](https://www.vektis.nl/uzovi-register). If the Uzovi is unknown, the Uzovi code is used as the name. The latest register is used to lookup the name for the code.
                              example: FBTO Zorgverzekeringen N.V.
                            concern:
                              type: string
                              description: The concern name, if any, otherwise the empty string.
                              example: ACHMEA
                            valid:
                              type: boolean
                              description: True if the insurer can be validated using the Uzovi table on the reference date.
                        gender:
                          $ref: '#/components/schemas/gender'
                        'n':
                          type: integer
                          format: int32
                          description: The number of unique patients in the group.
                          example: 7
        '400':
          $ref: '#/components/responses/ReqFailure'
        '401':
          $ref: '#/components/responses/JwtFailure'
        '403':
          description: Indicated practice is known but has not authorized ZOO to share this information with signer.
        '404':
          $ref: '#/components/responses/PatNotFound'
  /population/statistics/groupByItems:
    get:
      tags:
        - Population statistics
      operationId: groupByItems
      summary: Group-by items
      responses:
        '200':
          description: 'Returns a list of all available group-by items for the _population group-by end point_, but only if the items are available for the selected customer. A customer is selected by a JWT-claim or the AGB header. The output of this end point should be the same as the documentation for the groupByItems-parameter of the mentioned end point. '
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                example:
                  - age
                  - preferredDoctor
                  - insurer
                  - gender
                  - deprivedNeighborhood
        '400':
          $ref: '#/components/responses/ReqFailure'
        '401':
          $ref: '#/components/responses/JwtFailure'
        '404':
          $ref: '#/components/responses/PatNotFound'
  /population/statistics/deprivedNeighborhood:
    get:
      tags:
        - Population statistics
      operationId: populationStatisticsDeprivedNeighborhood
      summary: Deprived neighborhood
      description: A simple report with a count of all patients living in a deprived neighborhood or regular one based on the well-known postcode table.
      parameters:
        - $ref: '#/components/parameters/RefDateDefaultToday'
      responses:
        '200':
          description: |-
            Returns the counts of all patients divided into 3 categories:
            * Known to live in a deprived neighborhood
            * known to live in a regular neighborhood
            * Status of neighborhood unknown (for example, because living address of patient is not known or deprived status of that location is not known).
          content:
            application/json:
              schema:
                type: object
                required:
                  - deprived
                  - regular
                  - unknown
                properties:
                  deprived:
                    description: Number of patients living in a deprived neighborhood
                    type: integer
                    format: int32
                    minimum: 0
                    example: 42
                  regular:
                    description: Number of patients living in a regular neighborhood
                    type: integer
                    format: int32
                    minimum: 0
                    example: 256
                  unknown:
                    description: Number of patients either living in an unknown location or a known location with unknown depraved status
                    type: integer
                    format: int32
                    minimum: 0
                    example: 0
        '400':
          $ref: '#/components/responses/ReqFailure'
        '401':
          $ref: '#/components/responses/JwtFailure'
        '403':
          description: Indicated practice is known but has not authorized ZOO to share this information with signer.
        '404':
          $ref: '#/components/responses/PatNotFound'
  /population/statistics/deprivedNeighborhood/{neighborhood}:
    get:
      tags:
        - Population statistics
      operationId: populationStatisticsDeprivedNeighborhoodPatients
      summary: Deprived neighborhood, patients
      description: The list of patients belonging to one of the categories, see `neighborhood` below.
      parameters:
        - $ref: '#/components/parameters/RefDateDefaultToday'
        - name: neighborhood
          in: path
          schema:
            type: string
            enum:
              - deprived
              - regular
              - unknown
          example: deprived
          description: |-
            The neighborhood is derived from the postcode.
            If the postcode is not valid, e.g. not in the regular language defined by `[0-9]{4}\s*[a-zA-Z][a-zA-Z]`, then the neighborhood is 'unknown', otherwise the neighborhood is 'deprived' or 'regular'. The difference between the latter is based on national tables.
            NB: Asking for all patients in the `regular` group may result in access denied errors; these lists are generally large and not usually a worthwhile list to provide to medical professionals.
        - name: pii
          in: query
          example: true
          description: If false, limits the response to only patient ids.
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Returns the list of all patients from of the supplied category.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  required:
                    - category
                    - doctor
                    - patid
                    - patUnid
                    - feats
                  properties:
                    bsn:
                      $ref: '#/components/schemas/pat-BSN'
                    name:
                      $ref: '#/components/schemas/pat-Name'
                    gender:
                      $ref: '#/components/schemas/gender'
                    dob:
                      $ref: '#/components/schemas/date'
                    category:
                      $ref: '#/components/schemas/category'
                    doctor:
                      $ref: '#/components/schemas/doctor'
                    address:
                      $ref: '#/components/schemas/address'
                    contact:
                      $ref: '#/components/schemas/contact'
                    insurance:
                      $ref: '#/components/schemas/insurance'
                    patid:
                      $ref: '#/components/schemas/pat-patId'
                    patPubId:
                      $ref: '#/components/schemas/pat-patPubId'
                    patUnid:
                      $ref: '#/components/schemas/pat-patUnid'
                    startDate:
                      $ref: '#/components/schemas/date'
        '400':
          $ref: '#/components/responses/ReqFailure'
        '401':
          $ref: '#/components/responses/JwtFailure'
        '403':
          description: Indicated practice is known but has not authorized ZOO to share this information with signer.
        '404':
          $ref: '#/components/responses/PatNotFound'
  /population/statistics/employeeFeat:
    get:
      tags:
        - Population statistics
      operationId: populationStatisticsEmployeeFeat
      summary: Employee turnover
      description: Summaries the performance of employees expressed in feat count and turnover amounts. Only contract and national tariffs are used. Tariffs imported from any GPIS are ignored. Contract tariffs as registered by Zorg op Orde or, if not present, national tariffs as published by the government are used. Only to most recent years of national tariffs are available.
      parameters:
        - $ref: '#/components/parameters/Authorization'
        - name: periodStart
          in: query
          description: Start of the period (including) to summarize.
          schema:
            $ref: '#/components/schemas/date'
        - name: periodEnd
          in: query
          description: End of the period (excluding) to summarize.
          schema:
            $ref: '#/components/schemas/date'
        - $ref: '#/components/parameters/GpCodes'
          description: |-
            Restricts to the GP's which were medical responsible for the feat. Uses the GP at the time of the feat, or if not available, the GP responsible for the patient at the time of the GPIS-import. The GP at the time of the feat is the most accurate.

            The responsible GP is not written in the response, due the structure of the agreggation.
        - name: employees
          in: query
          description: 'Restricts the selection of feats to one or more employees: an employee executed the feat.'
          schema:
            $ref: '#/components/schemas/employee-alias'
        - name: excludeNilDeclarations
          in: query
          description: Declarations for which no tariff can determined, or which tariff equals zero, are omitted.
          schema:
            type: boolean
      responses:
        '200':
          description: Returns a object with a dictionary and an array of employees.
          content:
            application/json:
              schema:
                type: object
                properties:
                  dict:
                    $ref: '#/components/schemas/TermsDictionary'
                  employees:
                    type: array
                    items:
                      type: object
                      properties:
                        alias:
                          type: string
                          example: AA
                        name:
                          type: string
                          example: H. Huisman
                        periods:
                          type: array
                          items:
                            type: object
                            properties:
                              year:
                                type: number
                                example: 2024
                              month:
                                type: number
                                example: 5
                              feats:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    vektis:
                                      $ref: '#/components/schemas/FeatCode'
                                    alias:
                                      type: string
                                      example: C2
                                    count:
                                      type: number
                                      description: Count of the number of feats including feats without amount, except if those are excluded, see parameters.
                                      example: 21
                                    amount:
                                      type: number
                                      example: 48342
        '400':
          $ref: '#/components/responses/ReqFailure'
        '401':
          $ref: '#/components/responses/JwtFailure'
        '403':
          $ref: '#/components/responses/MandateMissing'
        '404':
          $ref: '#/components/responses/PatNotFound'
  /population/frequentUser/count:
    get:
      tags:
        - Frequent users
      operationId: populationFrequentUserCount
      summary: Visits report
      description: Patient population projected on the number of visits.
      parameters:
        - name: periodStart
          in: query
          description: Start of the period (including) to analyze.
          schema:
            $ref: '#/components/schemas/date'
        - name: periodEnd
          in: query
          description: End of the period (excluding) to analyze.
          schema:
            $ref: '#/components/schemas/date'
        - name: gpAgbs
          in: query
          description: |-
            If present, restrict report to patients registered to any of the GP AGBs listed here.
            The restriction is applied to the GP responsible for the patient now, not on the GP reponsislbe at the time of the feat.
          example: 01015678,01018765,01014321
          schema:
            type: array
            items:
              type: integer
        - name: gpMemocodes
          in: query
          description: |-
            If present, restrict report to patients registered to any of the GPs listed here; list the memocode as used in the GP Information System.
            The restriction is applied to the GP responsible for the patient now, not on the GP reponsislbe at the time of the feat.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Practitioner'
        - name: featCodes
          in: query
          description: 'The feats which are identified as time consuming or otherwise taking effort of the practice, defaults to: 12011,12411,12001,12401,12010,12410.'
          schema:
            $ref: '#/components/schemas/FeatCode'
        - name: patients
          in: query
          description: If present, restrict output to only patients in this list.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/pat-patId'
      responses:
        '200':
          description: An object with at least the frequency property which holds an array with the number of visits and their frequency.
          content:
            application/json:
              schema:
                type: object
                required:
                  - frequencies
                properties:
                  frequencies:
                    type: array
                    items:
                      type: object
                      properties:
                        visits:
                          type: integer
                        frequency:
                          type: integer
                      example:
                        - visits: 1
                          frequency: 355
                        - visits: 2
                          frequency: 240
                        - visits: 4
                          frequency: 25
        '400':
          $ref: '#/components/responses/ReqFailure'
        '401':
          $ref: '#/components/responses/JwtFailure'
        '403':
          $ref: '#/components/responses/MandateMissing'
        '404':
          $ref: '#/components/responses/PatNotFound'
  /population/frequentUser/patients:
    get:
      tags:
        - Frequent users
      operationId: populationFrequentUserPatients
      summary: Frequent users
      description: Lists the top n (1-50) frequent users (patients).
      parameters:
        - name: periodStart
          in: query
          description: Start of the period (including) to analyze.
          schema:
            $ref: '#/components/schemas/date'
        - name: periodEnd
          in: query
          description: End of the period (excluding) to analyze.
          schema:
            $ref: '#/components/schemas/date'
        - name: gpAgbs
          in: query
          description: |-
            If present, restrict report to patients registered to any of the GP AGBs listed here.
            The restriction is applied to the GP responsible for the patient now, not on the GP responsible at the time of the feat.
          schema:
            type: array
            items:
              type: integer
        - name: gpMemocodes
          in: query
          description: |-
            If present, restrict report to patients registered to any of the GPs listed here; list the memocode as used in the GP Information System.
            The restriction is applied to the GP responsible for the patient now, not on the GP responsible at the time of the feat.
          example: 01015678,01018765,01014321
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Practitioner'
        - name: featCodes
          in: query
          description: 'The feats which are identified as time consuming or otherwise taking effort of the practice, defaults to: 12011,12411,12001,12401,12010,12410.'
          schema:
            $ref: '#/components/schemas/FeatCode'
        - name: patients
          in: query
          description: If present, restrict output to only patients in this list.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/pat-patId'
        - name: pii
          in: query
          description: 'Allow personal identifying information in the response. Defaults to false if omitted. If false, only category, doctor, patid, patUnid and feats are in the response. In other words: they are always in the response, but can be extended with other pii properties, see non-required properties below.'
          example: true
          schema:
            type: boolean
        - name: limit
          in: query
          description: Limits the output to the top 1 to 50 of the frequent users (patients). Defaults to 20 if omitted or not in the specified range.
          schema:
            type: integer
            minimum: 1
            maximum: 50
      responses:
        '200':
          description: Responds with an array with patients. Only the top `limit` users are exported. The output is ranked with the most frequent user at position 0 of the array.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  required:
                    - category
                    - doctor
                    - patid
                    - patUnid
                    - feats
                  properties:
                    bsn:
                      $ref: '#/components/schemas/pat-BSN'
                    name:
                      $ref: '#/components/schemas/pat-Name'
                    gender:
                      $ref: '#/components/schemas/gender'
                    dob:
                      $ref: '#/components/schemas/date'
                    category:
                      $ref: '#/components/schemas/category'
                    doctor:
                      $ref: '#/components/schemas/doctor'
                    address:
                      $ref: '#/components/schemas/address'
                    contact:
                      $ref: '#/components/schemas/contact'
                    insurance:
                      $ref: '#/components/schemas/insurance'
                    patid:
                      $ref: '#/components/schemas/pat-patId'
                    patPubId:
                      $ref: '#/components/schemas/pat-patPubId'
                    patUnid:
                      $ref: '#/components/schemas/pat-patUnid'
                    feats:
                      type: object
                      properties:
                        featCode0:
                          type: object
                          description: The string featCode0 is replaced by an actual code, e.g. 12001.
                          properties:
                            description:
                              type: string
                              example: consult huisarts langer dan 20 minuten
                              description: The feat description is taken from the GPIS import.
                            'n':
                              type: number
                              description: The count of the feats with the given code for the patient.
                              example: 59
                        featCodeN:
                          type: object
                          properties:
                            description:
                              type: string
                              example: Consult regulier korter dan 5 minuten
                            'n':
                              type: number
                              example: 54
        '400':
          $ref: '#/components/responses/ReqFailure'
        '401':
          $ref: '#/components/responses/JwtFailure'
        '403':
          $ref: '#/components/responses/MandateMissing'
        '404':
          $ref: '#/components/responses/PatNotFound'
  /population/frequentUser/patient:
    get:
      tags:
        - Frequent users
      operationId: populationFrequentUserPatient
      summary: Feats
      description: Get the feats of a specific patient. Intended for use after the frequent user report. Is intended for statistical analysis purposes, does not replace the medical dossier.
      parameters:
        - name: periodStart
          in: query
          description: Start of the period (including) to analyze.
          schema:
            $ref: '#/components/schemas/date'
        - name: periodEnd
          in: query
          description: End of the period (excluding) to analyze.
          schema:
            $ref: '#/components/schemas/date'
        - name: gpAgbs
          in: query
          description: |-
            If present, restrict report to patients registered to any of the GP AGBs listed here.
            The restriction is applied to the GP responsible for the patient now, not on the GP responsible at the time of the feat.
          example: 01015678,01018765,01014321
          schema:
            type: array
            items:
              type: integer
        - name: gpMemocodes
          in: query
          description: |-
            If present, restrict report to patients registered to any of the GPs listed here; list the memocode as used in the GP Information System.
            The restriction is applied to the GP responsible for the patient now, not on the GP responsible at the time of the feat.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Practitioner'
        - name: featCodes
          in: query
          description: 'The feats which are identified as time consuming or otherwise taking effort of the practice, defaults to: 12011,12411,12001,12401,12010,12410.'
          schema:
            $ref: '#/components/schemas/FeatCode'
        - name: patId
          in: query
          schema:
            $ref: '#/components/schemas/pat-patId'
      responses:
        '200':
          description: Lists for exactly one patient all feats per day. All ICPC codes which can be found on a given day are added to the combination of feat and day. This causes duplicate output of the ICPC codes if two or more different feats are registered on the same day. This is due to a lack of the registration of the exact time of the contact moment in some GP information systems.
          content:
            application/json:
              schema:
                type: object
                properties:
                  dict:
                    $ref: '#/components/schemas/TermsDictionary'
                  feats:
                    type: array
                    items:
                      type: object
                      properties:
                        featCode:
                          type: integer
                          example: 12001
                        date:
                          $ref: '#/components/schemas/date'
                        employee:
                          type: string
                          description: The memocode as used in the GP Information System for the employee that is responsible for these feats.
                          example: RH
                        memoCode:
                          type: string
                          example: C2
                        description:
                          type: string
                          example: consult huisarts langer dan 20 minuten
                        patId:
                          $ref: '#/components/schemas/pat-patId'
                        icpc:
                          type: array
                          items:
                            type: string
                          example:
                            - S74.02
                            - Y07.00
                            - K87.00
        '400':
          $ref: '#/components/responses/ReqFailure'
        '401':
          $ref: '#/components/responses/JwtFailure'
        '403':
          $ref: '#/components/responses/MandateMissing'
        '404':
          $ref: '#/components/responses/PatNotFound'
  /qoc/careprograms:
    get:
      operationId: carePrograms
      tags:
        - Quality of Care
      summary: Care programs
      description: Enumerate all care programs (ketens) in which the customer participates.
      parameters:
        - $ref: '#/components/parameters/Authorization'
      responses:
        '200':
          description: Set of care programs (ketens).
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    careprogram:
                      $ref: '#/components/schemas/CareProgram-enum'
                    name:
                      description: |-
                        Title of this careprogram meant for humans. In other words, the same as `careprogram`, but in dutch and conforming to the naming conventions of the care group.
                        In particular, VVR/HVZ tend to have wildly different names (certain groups call it CVRM, others HVZ, others 'VRM - Hoog risico', and so forth).
                      type: string
                      example: VRM – Hoog Risico
        '401':
          $ref: '#/components/responses/NoAuth'
        '403':
          $ref: '#/components/responses/NoAccess'
  /qoc/indicatorsets:
    get:
      operationId: indicatorSets
      tags:
        - Quality of Care
      summary: Indicator sets
      description: |-
        List all available indicator sets. Includes all sets that the user is allowed to enable or preview, i.e. even ones that shouldn't be shown by default.

        This endpoint is also reachable using URL `/qoc/careprogram`, but that endpoint is deprecated.
      parameters:
        - name: carePrograms
          in: query
          description: A comma separated list of care program types, for example `DM,COPD`. The response is limited to the specified care programs.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/CareProgram-enum'
        - $ref: '#/components/parameters/Authorization'
      responses:
        '200':
          description: |-
            Indicator sets are returned.

            Examples:
            * <a href="examples/qoc_indicatorsets.1.json">Example complete response</a>
            * <a href="examples/qoc_indicatorsets.ui_example.png">Example UI render (somewhat outdated)</a>
          links:
            GetIndicatorSet:
              operationId: indicatorSet
              parameters:
                setKey: $response.body#/key
          content:
            application/json:
              schema:
                type: object
                properties:
                  indicatorsets:
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                          description: Key of the indicator set or casefinder.
                        name:
                          type: string
                          description: Something like `DM (Calisota)` – describes the careprogram itself (and not the purpose of this indicatorset - see `subName` for that).
                        subName:
                          type: string
                          description: Something like `Oproepen` or `Rapportage 75+` – describes the purpose of this indicatorset; a number of sets all with the same name but with different subNames can exist, representing different views and protocol approaches to the same care program. Omitted if not relevant (in that case `name` describes this set/casefinder fully).
                        description:
                          type: string
                          description: A longer description in dutch describing e.g. the chronic care condition covered by this set.
                        tags:
                          type: array
                          description: A list of simple short dutch strings describing properties of this set.
                        defaultShow:
                          type: boolean
                        favState:
                          type: string
                          description: Always "X".
                          example: X
                        type:
                          type: string
                          description: Either "indicatorset" or "casefinding".
                          example: indicatorset
                        careprogram:
                          $ref: '#/components/schemas/CareProgram-enum'
                          description: The kind of chronic care that this care program caters to. Can be omitted in cases where this care program doesn't cover a generally accepted protocolized chronic care condition. That is often the case with new research projects.
                        future:
                          type: boolean
                          description: This set is a sneak peek; it is not (yet) the official guideline, and is still being evaluated.
                        callup:
                          type: boolean
                          description: If this 'flavour' (as per `subName`) is intended to be used to call up patients and look to the future (this will be `true`) or if this set's intent is reporting and introspection, looking to the past (this will be `false`).
                        url:
                          type: string
                          description: Only provided for type "casefinder". Casefinders are not available via the API; redirect the user to this URL.
        '401':
          $ref: '#/components/responses/NoAuth'
        '403':
          $ref: '#/components/responses/NoAccess'
  /qoc/indicatorset/{setKey}:
    get:
      operationId: indicatorSet
      tags:
        - Quality of Care
      summary: Indicator set
      description: |-
        Provides indicators for a care program. An indicator set holds all indicators for a combination of a care program, reference date and a customer.
        Care groups and practices see different output. The authorisation for the care group to access care program data is taken in account.
      parameters:
        - name: setKey
          in: path
          description: The key as listed in the [/qoc/careprogram](#tag/Quality-of-Care/operation/carePrograms) response.
          required: true
          schema:
            type: string
          example: ZEL-dm
        - name: refDate
          in: query
          description: The date in `2023-04-01` format; defaults to the sensible date for the indicator set you query, which is generally the first day of either this quarter, or the next quarter.
          required: false
          schema:
            $ref: '#/components/schemas/date'
        - $ref: '#/components/parameters/Authorization'
      responses:
        '200':
          description: |-
            All data required to render an indicator set is returned.

            Examples:
              * <a href="examples/qoc_indicatorset.1.json">Example complete response</a>
              * <a href="examples/qoc_indicatorset.ui_example.png">Example UI render</a>
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndicatorSet'
        '401':
          $ref: '#/components/responses/NoAuth'
        '403':
          $ref: '#/components/responses/NoAccess'
        '404':
          description: The provided `setKey` doesn't refer to a valid program.
  /qoc/indicator/{setKey}/{indicatorKey}/patients:
    get:
      operationId: indicatorSetPatients
      tags:
        - Quality of Care
      summary: Indicator, patient detail
      description: Show per-patient details for a specific indicator.
      parameters:
        - name: setKey
          in: path
          description: The key as listed in the `CareProgram` schema.
          required: true
          schema:
            type: string
          example: ZEL-dm
        - name: indicatorKey
          in: path
          description: The key as listed in the indicatorset.
          schema:
            type: string
            example: ZOO-dm2-hb-3
        - name: refDate
          in: query
          description: The date in `2023-04-01` format; defaults to the first day in the next quarter, e.g. on april 5th 2023, defaults to `2023-07-01`.
          required: false
          schema:
            $ref: '#/components/schemas/date'
        - $ref: '#/components/parameters/Authorization'
      responses:
        '200':
          description: Some descriptive text explaining this indicator in detail as well as a per-patient report.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndicatorDetail'
        '401':
          $ref: '#/components/responses/NoAuth'
        '403':
          $ref: '#/components/responses/NoAccess'
        '404':
          description: The provided `setKey` and/or `indicatorKey` do not refer to a valid program or indicator.
  /qoc/indicator/{setKey}/{indicatorKey}/participants:
    get:
      operationId: indicatorSetParticipants
      tags:
        - Quality of Care
      summary: Indicator, practice details
      description: Show per-practice details for each practice in a group for a specific indicator.
      parameters:
        - name: setKey
          in: path
          description: The key as listed in the `CareProgram` schema.
          required: true
          schema:
            type: string
          example: ZEL-dm
        - name: indicatorKey
          in: path
          description: The key as listed in the indicator set.
          required: true
          schema:
            type: string
            example: ZOO-dm2-hb-3
        - name: refDate
          in: query
          description: The date in `2023-04-01` format; defaults to the first day in the next quarter, e.g. on april 5th 2023, defaults to `2023-07-01`.
          required: false
          schema:
            $ref: '#/components/schemas/date'
        - $ref: '#/components/parameters/CareGroup'
        - $ref: '#/components/parameters/Authorization'
      responses:
        '200':
          description: Some descriptive text explaining this indicator in detail as well as per-practice stats that can be rendered as a table or graph.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndicatorParticipants'
        '401':
          $ref: '#/components/responses/NoAuth'
        '403':
          $ref: '#/components/responses/NoAccess'
        '404':
          description: The provided `setKey` and/or `indicatorKey` do not refer to a valid program or indicator.
  /qoc/callupList/{setKey}:
    get:
      operationId: callupList
      tags:
        - Quality of Care
      summary: Call-up status
      description: |-
        Load call-up status for patients in a care program.

        Returns each patient in a care program along with the progress on required or suggested measurements indicated for this care program.
        Also includes any custom callup policies as part of the response, and the callup plan for this quarter.

        Every quarter, each patient is assigned a callup plan for just that quarter (it resets for every quarter). A callup plan
        is either 'call them up' or 'do not call them up'. Most patients start off in an 'open' state where no decision on whether
        to call them up has been made yet.

        Callup policies are different: They aren't per quarter; instead they represent medical decisions that impact their chronic
        care. For example, 'this patient is not available for checkups until next year', or 'this patient is an amputee; do not
        consider a missing analysis of the feet as relevant'. They can have an explicitly chosen end date.

        Call up plans have a default. Usually it is 'open' (no decision yet made on whether to call them up this quarter or not),
        but explicitly set policies as well as implicit policies chosen by the care group can affect this. For example, if a
        policy is set that the patient is not available for a few quarters, the plan defaults to 'do not call up' instead.

        To enable making clear to the user via the UI exactly what choices have been made, the API services differentiates between
        what the default behaviour of a plan is; this is called the `byPolicy` plan - versus what the user explicitly chose.

        In other words, a patient that defaults to 'do not call up' can be differentiated from a patient where an explicit choice
        was made to set their callup plan for the quarter to 'do not call up'. A patient that has defaulted to 'do not call up' can
        have that value change when the policies change; a patient that was explicitly set to 'do not call up' will not change the
        plan even if underlying policies change.

        Policies are set vie the `/qoc/callupPolicy` endpoint.
      parameters:
        - name: setKey
          in: path
          description: The key as listed in the `CareProgram` schema.
          required: true
          schema:
            type: string
          example: ZEL-dm
        - name: refDate
          in: query
          description: The date in `2023-04-01` format; defaults to the first day in the next quarter, e.g. on april 5th 2023, defaults to `2023-07-01`.
          required: false
          schema:
            $ref: '#/components/schemas/date'
        - name: birthMonth
          in: query
          description: |-
            Restricts the patient list to those born in the specified month and those with no birthdate (rare case). The list of gp's is limited to those who are responsible to the patients in the restricted list. The initial calculation of the call-up list is not affected by the parameter.

            If the parameter is omitted or specified outside its boundaries, then all patients are returned.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 12
        - name: addr
          in: query
          required: false
          description: Request inclusion of address information
          schema:
            type: boolean
        - name: bsn
          in: query
          required: false
          description: Request inclusion of BSN information (dutch social security number)
          schema:
            type: boolean
        - name: email
          in: query
          required: false
          description: Request inclusion of email addresses
          schema:
            type: boolean
        - $ref: '#/components/parameters/Authorization'
      responses:
        '200':
          description: list of patients
          content:
            application/json:
              schema:
                type: object
                properties:
                  gpis:
                    $ref: '#/components/schemas/GPIS'
                  key:
                    $ref: '#/components/schemas/properties-key'
                  name:
                    $ref: '#/components/schemas/properties-name'
                  careprogram:
                    $ref: '#/components/schemas/CareProgram-enum'
                  refDate:
                    $ref: '#/components/schemas/date'
                  calculating:
                    $ref: '#/components/schemas/calculating'
                  doctors:
                    description: |-
                      Lists all relevant doctors. A doctor is relevant if they are responsible
                      for at least 1 patient in the list.
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          description: The name (or possibly memocode; something an employee of the practice will recognize) of the general practitioner.
                          type: string
                        agb:
                          description: If known, the AGB code of this general practitioner.
                          type: integer
                          format: int32
                          minimum: 1
                          maximum: 99999999
                          example: 1099999
                      required:
                        - name
                  indicators:
                    type: array
                    description: One entry for each kind of measurement that (may) require call-up.
                    items:
                      type: object
                      properties:
                        title:
                          description: The title of this indicator
                          type: string
                          example: Bloeddruk
                        key:
                          description: Unique identifier, not to be shown to the user, for referring to this indicator in other API calls
                          type: string
                          example: ZEL-dm2-bp-result
                        optional:
                          description: If present, this indicator is optional, and the value contains dutch human readable text explaining why.
                          type: string
                          example: Volgens HKN protocol is BMI meten optioneel bij Astma patiënten; echter stelt het protocol wel een relatie tussen overgewicht en de mate van klachten.
                        focus:
                          description: |-
                            Caregroups can choose key performance indicators; such indicators are considered 'focus' indicators.
                            Focus indicators tend to be temporary; most caregroups adjust them yearly or every other year.
                          type: boolean
                          example: false
                      required:
                        - title
                        - key
                        - focus
                  patients:
                    type: array
                    items:
                      type: object
                      properties:
                        patPubId:
                          $ref: '#/components/schemas/pat-patPubId'
                        patUnid:
                          $ref: '#/components/schemas/pat-patUnid'
                        doctor:
                          type: integer
                          format: int32
                          description: 'An index (0-based) into the `doctors` entry: This is the GP responsible for this patient.'
                        chosenStatus:
                          type: string
                          description: |-
                            The callup plan explicitly chosen via an earlier call to the `/qoc/callupList/setStatus` endpoint.

                            The chosen status always defaults to `byPolicy` which indicates that the actual status will be derived
                            by analysing explicit and implicit policies. This 'by policy' status is provided via `byPolicyStatus`.
                          enum:
                            - byPolicy
                            - callUp
                            - dontCallUp
                            - scheduled
                          example: byPolicy
                        byPolicyStatus:
                          type: string
                          description: |-
                            The callup plan that applies if no explicit choice is made (i.e. the default choice - `byPolicy`).

                            This status is derived by analysing the care group's policies as well as any explicit policies set
                            via the `/qoc/callupPolicy` endpoint.

                            `open` means: Whether to call this patient up this quarter hasn't been decided yet, and the policies
                            do not suggest either choice as a default.
                          enum:
                            - open
                            - callUp
                            - dontCallUp
                        status:
                          type: string
                          description: |-
                            Provided by convenience: It's the value of `chosenStatus`, unless that is `byPolicy`, in which case
                            it is the value of `byPolicyStatus`. In other words, the status that applies to this patient.
                          enum:
                            - open
                            - callUp
                            - dontCallUp
                            - scheduled
                          example: open
                        address1:
                          type: string
                          description: The first line of this patient's postal address (Street name and number, generally).
                          example: Dorpsstraat 1
                        city:
                          type: string
                          description: Patient lives in this city or township.
                          example: Nowhereville
                        postcode:
                          type: string
                          description: Postcode of the patient.
                          example: 1234AA
                        bsn:
                          type: integer
                          minimum: 1
                          maximum: 999999999
                          format: int32
                          description: The BSN (dutch social security number) of the patient.
                          example: 123456789
                        dob:
                          $ref: '#/components/schemas/date'
                          description: Date of birth of the patient.
                        email:
                          type: string
                          format: email
                          description: Email address of the patient.
                          example: foo@bar.fake
                        state:
                          type: string
                          description: |-
                            A string containing 1 character for each indicator as listed in `indicators`.

                            This character represents the patient's call-up state for that indicator:
                              
                            * `-` – This indicator is not relevant for this patient; no call-up needed.
                            * `R` – This is an optional indicator, but, the patient doesn't have this measurement.
                            * `0` – This is a required indicator and the patient doesn't have it.
                            * `1` – The patient has this measurement; but unless it is measured again, next quarter it'll be too long ago and no longer counts.
                            * `2`-`8` – `2` is like `1`, except the measurement lasts for 2 quarters up to 8 quarters.
                            * `+` – The measurement lasts for 9 or more quarters (for example, the measurement only needs to be done once ever and it has been done).
                            * `x` – unknown situation (should not occur).
                          example: 0017-R-0
                        policies:
                          type: array
                          description: |-
                            Lists all explicitly chosen policies (set via `qoc/callupPolicy`) that apply to this
                            patient.
                          items:
                            type: object
                            properties:
                              type:
                                type: string
                                enum:
                                  - PatientIndicator
                                  - PatientSnoozed
                                description: |-
                                  The kind of policy this is.

                                  `PatientSnoozed` indicates the patient is not available for a limited period of time and thus isn't a candidate for calling up.

                                  `PatientIndicator` indicates an alternate frequency has been chosen for a specific indicator for this specific patient.
                                example: PatientIndicator
                              indicatorKey:
                                type: string
                                description: Only set for `PatientIndicator`. Which indicator has a custom frequency.
                                example: ZEL-dm2-bp-result
                              expires:
                                type: string
                                $ref: '#/components/schemas/date'
                                description: Date in ISO8601 format; if omitted does not expire. It is considered expired _on_ the stated date.
                              frequency:
                                type: string
                                description: |-
                                  For type `PatientIndicator` only (otherwise, not sent). Indicates that this indicator should be measured
                                  with a different frequency than what this care program by default suggests. The letter for this indicator in the `state` string
                                  takes this alternate frequency into account (or, is rendered as a `-`, indicating 'not relevant', if `never` is the custom frequency).
                                enum:
                                  - quarter
                                  - sixMonths
                                  - year
                                  - twoYear
                                  - threeYear
                                  - fiveYear
                                  - never
                                example: sixMonths
                              reason:
                                type: string
                                description: 'A reason for a policy can be provided when it is set, and is returned here. Omitted if not provided. '
                                example: Jannie zit tot eind december op een boorplatform.
                              employee:
                                $ref: '#/components/schemas/employee-string'
                              timestamp:
                                type: string
                                description: The policy was created (set) at this time.
                                $ref: '#/components/schemas/dateTimeZ'
                            required:
                              - type
                      required:
                        - patUnid
                        - doctor
                        - byPolicyStatus
                        - chosenStatus
                        - status
                        - dob
                        - state
                required:
                  - gpis
                  - key
                  - name
                  - refDate
                  - calculating
        '401':
          $ref: '#/components/responses/NoAuth'
        '403':
          $ref: '#/components/responses/NoAccess'
        '404':
          description: The provided `setKey` doesn't refer to a valid program.
  /qoc/callupList/setStatus:
    post:
      tags:
        - Quality of Care
      operationId: setPatientCallupStatus
      summary: Call-up status
      description: Set call-up status for patients in a care program.
      parameters:
        - name: BSN
          in: header
          deprecated: true
          description: If the `bsns` key in de request body form is omitted, it can be replaced by this HTTP header. Supply a comma separated list of BSN's. The further processing is the same as the `bsns` key in the request body, including the limit on the size of the list.
          example: 612345671,123456782,123456789
          schema:
            type: array
            items:
              $ref: '#/components/schemas/pat-BSN'
      requestBody:
        description: The request is designed to set the status of several patients, specified by patId (mensId) or BSN, at once. The endpoint is idempotent for the combination of careprogram, callUpStatus and BSN or patId. That means that the call-up status for a patient in a certain care program is just set once, until a new status is set. As a consequence only the employee who set first a certain status is stored, until somebody else (or the same employee) overwrites the status.
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                careprogram:
                  description: The kind of chronic care you want to set the call up status for.
                  $ref: '#/components/schemas/CareProgram-enum'
                callUpStatus:
                  type: string
                  enum:
                    - byPolicy
                    - callUp
                    - dontCallUp
                    - scheduled
                  example: callUp
                employee:
                  $ref: '#/components/schemas/employee-alias'
                quarter:
                  $ref: '#/components/schemas/date'
                  description: |-
                    Callup plans are specific to a single quarter and are returned only when asking for callup lists with this quarter
                    as the `refDate`. Defaults to 'next quarter' (i.e. on April 5th, would default to July 1st).
                bsns:
                  type: array
                  items:
                    $ref: '#/components/schemas/pat-BSN'
                    maxItems: 1000
                  example: 612345671,123456782,123456789
                  description: BSNs consisting only of zeros or only of nines or the empty BSN are ignored, i.e. BSNs matching regex `^0*|9*$` are ignored. BSNs are NOT checked to be valid ('elfproef'). BSNs may be zero-padded but don't have to be. One of `bsns` or `patIds` must be provided (but not both).
                patIds:
                  type: array
                  items:
                    $ref: '#/components/schemas/pat-patId'
                    maxItems: 1000
                  example: 10012,32122,1212
                  description: patient GPIS ids. One of `bsns` or `patIds` must be provided (but not both).
              required:
                - careprogram
                - callUpStatus
                - employee
              minItems: 4
      responses:
        '200':
          description: |-
            BSNs or patIds whose status has actually updated. BSNs or patIds which were not known in the GPIS are ignored and not returned here.
            The caller should determine the difference between the two sets to get the ignored patients. If a BSN matched more than one patient, all these patients were updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  bsns:
                    type: array
                    items:
                      type: integer
                    example:
                      - 612345671
                      - 123456782
                  patIds:
                    type: array
                    items:
                      type: integer
                    example:
                      - 10012
                      - 32122
                minItems: 1
                maxItems: 1
        '401':
          $ref: '#/components/responses/NoAuth'
        '403':
          $ref: '#/components/responses/NoAccess'
  /qoc/callupPolicy:
    get:
      tags:
        - Quality of Care
      operationId: getCallupPolicy
      summary: Call-up policy
      description: Gets all call-up policies of a patient for all indicators in which the patient participates, or for a specific indicator. Parameters are optional and simply filter the response; in other words, without parameters all policies are returned.
      parameters:
        - name: policyType
          in: query
          schema:
            $ref: '#/components/schemas/CallupPolicyType-enum-short'
        - name: patUnid
          in: query
          schema:
            $ref: '#/components/schemas/pat-patUnid'
            description: Show only policies for patients that match this unid. Not allowed if asking for `UserIndicator`.
        - name: bsn
          in: query
          schema:
            $ref: '#/components/schemas/pat-BSN'
            description: Show only policies for patients that match this bsn. Not allowed if asking for `UserIndicator`.
        - name: indicatorKey
          in: query
          description: The version suffix of the indicator is ignored. Only for type `UserIndicator` and `PatientIndicator`.
          schema:
            type: string
            example: ZOO-dm2-hb-1
        - name: refDate
          in: query
          description: Return only policies that haven't expired at this date. Defaults to 'next quarter').
          schema:
            type: string
            $ref: '#/components/schemas/date'
      responses:
        '200':
          description: All policies that match the supplied filter conditions.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    policyType:
                      $ref: '#/components/schemas/CallupPolicyType-enum-short'
                    patUnid:
                      $ref: '#/components/schemas/pat-patUnid'
                    indicatorKey:
                      type: string
                      example: ZOO-dm2-hb
                    userId:
                      type: integer
                      example: 123456
                    expires:
                      $ref: '#/components/schemas/date'
                      example: '2026-04-01'
                    frequency:
                      $ref: '#/components/schemas/CallupPolicyFrequency'
                      example: never
                    reason:
                      type: string
                      example: Zit op een boorplatform.
                    employee:
                      $ref: '#/components/schemas/employee-string'
                    timestamp:
                      $ref: '#/components/schemas/dateTime'
        '401':
          $ref: '#/components/responses/NoAuth'
        '403':
          $ref: '#/components/responses/NoAccess'
    post:
      tags:
        - Quality of Care
      operationId: postCallupPolicy
      summary: Call-up policy
      description: Set a call-up policy. Policies last until a specific expiry (or forever). See the descriptions of policy types to get an idea of what policies do and what they represent.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                policyType:
                  $ref: '#/components/schemas/CallupPolicyType-enum-full'
                patUnid:
                  $ref: '#/components/schemas/pat-patUnid'
                  example: 123456
                bsn:
                  $ref: '#/components/schemas/pat-BSN'
                indicatorKey:
                  description: The key of the indicator as listed in the indicator set. The version of the indicator is ignored (if the string ends in a dash and a number, those are stripped). Only relevant for `IndicatorUser` and `UserIndicator`.
                  example: ZOO-dm2-hb-3
                  type: string
                reason:
                  type: string
                  description: An optional human written reason for why the policy is being applied.
                  example: Zit op een boorplatform.
                expires:
                  description: If provided, this policy does not apply on and after this date. Mandatory for certain types of policy.
                  $ref: '#/components/schemas/date'
                frequency:
                  $ref: '#/components/schemas/CallupPolicyFrequency'
                employee:
                  $ref: '#/components/schemas/employee-string'
              required:
                - policyType
                - employee
      responses:
        '204':
          description: If the policy has been processed without any errors.
        '401':
          $ref: '#/components/responses/NoAuth'
        '403':
          $ref: '#/components/responses/NoAccess'
    delete:
      tags:
        - Quality of Care
      operationId: deleteCallupPolicy
      summary: Call-up policy
      description: Unset a call-up policy.
      parameters:
        - name: policyType
          in: query
          schema:
            $ref: '#/components/schemas/CallupPolicyType-enum-short'
        - name: patUnid
          in: query
          schema:
            $ref: '#/components/schemas/pat-patUnid'
            example: 123456
        - name: bsn
          in: query
          schema:
            $ref: '#/components/schemas/pat-BSN'
        - name: indicatorKey
          in: query
          description: The version suffix of the indicator is ignored (if any). Only relevant for `IndicatorUser` and `UserIndicator`.
          schema:
            type: string
            example: ZOO-dm2-hb-1
        - name: reason
          in: query
          description: Some random string describing the reason. May be omitted.
          schema:
            type: string
        - name: employee
          description: Employee who withdraws the policy for the patient and indicator combination.
          in: query
          schema:
            $ref: '#/components/schemas/employee-string'
  /qoc/list-groups:
    get:
      operationId: indicatorReportGroups
      tags:
        - Quality of Care
      summary: Indicator, care groups
      description: Show all care groups available for indicator reports. A group is a group of GP practices that do (part) of chronic care together.
      parameters:
        - name: refDate
          in: query
          description: The date in `2023-04-01` format; defaults to the first day in the next quarter, e.g. on april 5th 2023, defaults to `2023-07-01`.
          required: false
          schema:
            $ref: '#/components/schemas/date'
      responses:
        '200':
          description: A list of available groups.
          content:
            application/json:
              schema:
                type: object
                properties:
                  refDate:
                    description: 'Groups reported are available for this date (dutch: _peildatum_).'
                    $ref: '#/components/schemas/date'
                  groups:
                    description: A list of available groups.
                    type: array
                    items:
                      description: A tag (generally lower-case, no spaces).
                      type: string
                      example: hwf
                required:
                  - refDate
                  - groups
        '401':
          $ref: '#/components/responses/NoAuth'
        '403':
          $ref: '#/components/responses/NoAccess'
  /qoc/participating-practices:
    get:
      operationId: participatingGroups
      tags:
        - Quality of Care
      summary: Data quality
      description: Show each participating GP practice as well as the status of their data for a given indicator report and a given group.
      parameters:
        - name: setKey
          in: query
          description: The key as listed in the `CareProgram` schema. If omitted, information about participating in a specific care program will not be provided.
          required: false
          schema:
            type: string
          example: ZEL-dm
        - name: group
          in: query
          description: The key as listed in the `list-groups` endpoint. Defaults to the only allowed group if the authentication party only has one; otherwise required.
          required: false
          schema:
            type: string
          example: hwf
        - name: refDate
          in: query
          description: The date in `2023-04-01` format; defaults to the first day in the next quarter, e.g. on april 5th 2023, defaults to `2023-07-01`.
          required: false
          schema:
            $ref: '#/components/schemas/date'
      responses:
        '200':
          description: A list of practices participating in this group.
          content:
            application/json:
              schema:
                type: object
                properties:
                  group:
                    description: The chosen group (repeats `group` parameter if present, otherwise, the group defaulted to for authenticating user).
                    type: string
                    example: hwf
                  calculatedAt:
                    description: '*OPTIONAL*. The timestamp when the group average was calculated. If not present, no group average calculation is available.'
                    $ref: '#/components/schemas/dateTime'
                  refDate:
                    description: 'Groups reported are available for this date (dutch: _peildatum_).'
                    $ref: '#/components/schemas/date'
                  key:
                    description: Repeats the `setKey` parameter, if present.
                    type: string
                    example: ZOO-dm
                  title:
                    description: The title of the requested indicator set, if `setKey` was present.
                    type: string
                    example: Diabetes Mellitus type 2
                  participants:
                    description: A list of practices in this group.
                    type: array
                    items:
                      type: object
                      properties:
                        agb:
                          description: The AGB code for this practice.
                          type: number
                          example: 1012345
                        name:
                          description: The name of this practice.
                          type: string
                          example: Huisartsenpraktijk Mien Dobbelsteen
                        gpis:
                          description: The type of GP Information System
                          type: string
                        exclusionReason:
                          description: |-
                            If present, this GP is excluded from this care program. The value describes (dutch, *HTML*) why.
                            If not present, `mostRecentDataAvailable` will be available.
                          type: string
                        calculationBasedOn:
                          description: |-
                            If present, this GP practice is calculated for this refDate for this care program, and the calculation
                            is based on a snapshot of GPIS data at this instant.
                          $ref: '#/components/schemas/dateTime'
                        mostRecentDataAvailable:
                          description: |-
                            If present, this GP practice's most recent available data is a GPIS snapshot with GPIS data at this instant.
                            Usually equal to `calculationBasedOn`, but can be newer. If not present, this GP practice has no data available.
                          $ref: '#/components/schemas/dateTime'
                      required:
                        - agb
                        - name
                        - gpis
                required:
                  - group
                  - refDate
                  - participants
        '401':
          $ref: '#/components/responses/NoAuth'
        '403':
          $ref: '#/components/responses/NoAccess'
        '404':
          description: The provided `group` and/or `setKey` do not refer to a valid group or program.
  /customer/careprogram:
    get:
      operationId: getCustomerCareProgram
      tags:
        - Customer management
      summary: Practices and care programs
      description: |-
        Gets all practices of a care group and their participation in a care program.

        Enumerates all practices for which the current customer (user) is responsible in the care group. The customer identified with the JWT must be the group manager. The care group must be responsible for the underlying practices. Some care groups are organized in a way that they are not allowed to process data of the member practices. For these care groups no practices are shown.

        Only care programs to which the practice was added by the authorised care group are shown. That means if a practice moves to another care group, then the registered care programs are gone.

        If the JWT identifies a single practice, then API runs in bare mode. The response in this mode has the same structure, but the list of care programs of the care group is always empty and the list of practices holds exactly one practice.
      parameters:
        - name: refDate
          in: query
          description: If omitted, today is taken.
          schema:
            $ref: '#/components/schemas/date'
        - name: agbs
          in: query
          description: |-
            If the requesting entity is a care group, all GP practices in the group will be returned; this parameter can be used to filter the list, so
            that only those GP practices with one of the AGBs listed here are returned. If the requesting entity is a single GP practice, this parameter
            is ignored.
          example: 12345678,23456789
          schema:
            type: array
            items:
              $ref: '#/components/schemas/agb'
      responses:
        '200':
          description: care program inclusions status of all relevant GP practices.
          content:
            application/json:
              schema:
                type: object
                properties:
                  caregroup:
                    type: object
                    description: Information about the care group itself; will not be included if the authorizing entity is a GP practice.
                    properties:
                      name:
                        type: string
                        description: Identifying tag name of the care group.
                        example: demo_fabel
                      careprograms:
                        description: All care programs contracted by the care group. Subtract from this set the active care programs from any practice reported in `practices` to know which care programs they may want to activate.
                        example:
                          - OuderenZorg
                          - DM
                          - COPD
                          - HVZ
                          - VVR
                        type: array
                        items:
                          $ref: '#/components/schemas/CareProgram-enum'
                  practices:
                    type: array
                    items:
                      type: object
                      properties:
                        agb:
                          $ref: '#/components/schemas/agb'
                        name:
                          type: string
                        gpis:
                          $ref: '#/components/schemas/GPIS'
                        careprograms:
                          type: array
                          items:
                            type: object
                            properties:
                              careprogram:
                                $ref: '#/components/schemas/CareProgram-enum'
                              periodStart:
                                $ref: '#/components/schemas/date'
                              periodEnd:
                                $ref: '#/components/schemas/date'
                              active:
                                type: boolean
                                description: True if today is on or after `periodStart` and before `periodEnd`.
                            required:
                              - careprogram
                              - periodStart
                              - active
        '401':
          $ref: '#/components/responses/NoAuth'
        '403':
          $ref: '#/components/responses/NoAccess'
    post:
      tags:
        - Customer management
      operationId: setCustomerCareProgram
      summary: Add a practice to a care program.
      description: |-
        Allows a care group manager to configure which care programs are actively participated in by a GP practice.

        The caller must authorize itself as a care group (manager).

        The care group must be allowed to take responsibility for the practices it holds. If not, the request is ignored and an empty Json-object is sent back to the caller, indicating that processing was not successful.

        The practice must be one of the care group practices. If not, the request is ignored and an empty Json-object is sent back to the caller.

        In all other cases a Json-object containing the same data as in the request with a timestamp added is sent back in the response.

        The operation is idempotent for the combination of: `careprogram`, `agb`, `periodStart` and `periodEnd`. If these are the same in any _subsequent call_ the request is processed as being fully accepted, showing the request data in the response,
        but the `employee` and `timestamp` aren't updated in the database. The timestamp and employee of the original submit to this API is included in the response instead of the provided values.
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                careprogram:
                  description: The kind of care program that the practice participates in.
                  $ref: '#/components/schemas/CareProgram-enum'
                agb:
                  description: The AGB of the practice (not the doctor).
                  $ref: '#/components/schemas/agb'
                periodStart:
                  description: If `periodEnd` is supplied, then the `periodStart` must meet the condition that `periodStart` < `periodEnd`. The period starts on `periodStart` and ends on the day before `periodEnd`, so the start date is inclusive and end date exclusive.
                  $ref: '#/components/schemas/date'
                periodEnd:
                  description: See `periodStart`.
                  $ref: '#/components/schemas/date'
                employee:
                  type: string
                  description: The employee that is adding the practice. Any string is accepted, but it is recommended to use a employee code derived from this API.
              required:
                - careprogram
                - agb
                - periodStart
                - employee
      responses:
        '200':
          description: If and only if, the request was successful processed down to the database, a Json-object with the following properties is sent back to the caller, otherwise a non 200 HTTP response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  employee:
                    type: string
                  timestamp:
                    $ref: '#/components/schemas/dateTime'
                  careprogram:
                    $ref: '#/components/schemas/CareProgram-enum'
                  agb:
                    $ref: '#/components/schemas/agb'
                  periodStart:
                    $ref: '#/components/schemas/date'
                  periodEnd:
                    $ref: '#/components/schemas/date'
        '401':
          $ref: '#/components/responses/NoAuth'
        '403':
          $ref: '#/components/responses/NoAccess'
  /customer/careprogram/periodEnd:
    post:
      tags:
        - Customer management
      operationId: setCustomerCareProgramPeriodEnd
      summary: Update only the period end
      description: Updates only the period end date of the participation of a practice in a care program. This is equivalent to submitting a new participation to this API, but, the `periodStart` parameter is not needed. Requires that this practice already participates in the provided care program (and that participation will have its end date updated).
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                careprogram:
                  description: The kind of care program that the practice participates in.
                  $ref: '#/components/schemas/CareProgram-enum'
                agb:
                  description: The AGB of the practice (not the doctor).
                  $ref: '#/components/schemas/agb'
                employee:
                  type: string
                  description: The employee that is adding the practice. Any string is accepted, but it is recommended to use a employee code derived from this API.
                periodEnd:
                  description: The end of the period of the participation. Allowed to be not set or empty, when no end date is known. If set, `periodEnd` must be at least a day after the `periodStart` which is stored for the combination of `careprogram` and `agb`.
                  $ref: '#/components/schemas/date'
              required:
                - careprogram
                - agb
                - employee
      responses:
        '200':
          description: If the request was successfully processed, a Json-object with the following properties is send back to the caller, otherwise a non 200 HTTP response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  employee:
                    type: string
                  timestamp:
                    $ref: '#/components/schemas/dateTime'
                  careprogram:
                    $ref: '#/components/schemas/CareProgram-enum'
                  agb:
                    $ref: '#/components/schemas/agb'
                  periodStart:
                    $ref: '#/components/schemas/date'
                  periodEnd:
                    $ref: '#/components/schemas/date'
        '401':
          $ref: '#/components/responses/NoAuth'
        '403':
          $ref: '#/components/responses/NoAccess'
  /customer/basic:
    get:
      operationId: customerBasicGet
      tags:
        - Customer management
      summary: Basic info
      parameters:
        - name: agb
          in: query
          description: |-
            AGB of the practice for which basic info is requested.
            If the requesting entity is a single GP practice, this parameter can be omitted.
          schema:
            $ref: '#/components/schemas/agb'
      responses:
        '200':
          description: Basic information of a practice.
          content:
            application/json:
              schema:
                type: object
                properties:
                  practice:
                    type: object
                    properties:
                      name:
                        type: string
                      officialName:
                        type: string
                      practiceAgb:
                        description: The AGB of the practice, if the customer in the response is a practice, otherwise omitted. One of practiceAgb or institutionAgb is always present.
                        $ref: '#/components/schemas/agb'
                      institutionAgb:
                        description: The AGB of the institution, if the customer is a care group or other institute, otherwise omitted. One of practiceAgb or institutionAgb is always present.
                        $ref: '#/components/schemas/agb'
                      gpisMethod:
                        description: The current GPIS type and how medical dossiers are transferred to Zorg op Orde.
                        example: HealthConnected (automatische koppeling)
                      lastImport:
                        $ref: '#/components/schemas/GPIS'
                      doctors:
                        description: AGBs of the doctors working in the practice.
                        type: array
                        items:
                          $ref: '#/components/schemas/doctor'
                      address:
                        type: object
                        properties:
                          address1:
                            type: string
                            description: The first line of the practice postal address (street name and house number, generally).
                            example: Dorpsstraat 1
                          postcode:
                            $ref: '#/components/schemas/postcode'
                          city:
                            $ref: '#/components/schemas/city'
                      contact:
                        type: object
                        properties:
                          tel:
                            type: string
                            example: '0612345678'
                          email:
                            type: string
                            example: M.Dobbelsteen@zorgoporde.nl
                      share_authorizations:
                        description: The GP has granted permission to share certain aspects of the EPD data with the listed third parties.
                        type: array
                        example:
                          - KSYOS_FUNDUS
                        items:
                          type: string
                      dataProcessing:
                        type: object
                        properties:
                          controllers:
                            description: A list of personnel responsible for the data. Usually the practice owner.
                            type: array
                            example:
                              - Mien Dobbelsteen
                              - Lydie van der Ploeg
                            items:
                              type: string
                          agreement:
                            type: object
                            properties:
                              signedBy:
                                description: Full name of the signer.
                                type: string
                                example: Lydie van der Ploeg
                              signedOn:
                                description: Date of signing the data processing agreement.
                                example: 20160501T1344
                                $ref: '#/components/schemas/date'
                    required:
                      - name
                      - officialName
        '400':
          description: If the specified customer is not a practice but some other entity, e.g. a care group.
        '401':
          $ref: '#/components/responses/NoAuth'
        '403':
          description: |-
            User is not allowed to access this API endpoint, or,
            the practice identified by the `agb` parameter does not have a relationship with the
            user (for example, they do not belong to your care group).
    post:
      operationId: customerBasicPost
      tags:
        - Customer management
      summary: Basic info
      description: Only certain properties of a practice can be updated. After updating the same response is outputted as when using GET.
      parameters:
        - name: agb
          in: query
          description: |-
            AGB of the practice for which basic info is requested.
            If the requesting entity is a single GP practice, this parameter can be omitted.
          schema:
            $ref: '#/components/schemas/agb'
      requestBody:
        description: |-
          When authorized as a practice the address and contact data can be changed.
          Currently, if authorized as a care group, no properties can be changed.

          Properties can be omitted if you do not want to change them. `address1` and `postcode` cannot be set to empty.
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                address1:
                  type: string
                  description: The first line of the practice postal address (street name and house number, generally).
                postcode:
                  description: Any valid Dutch postcode, with or without whitespacing and in lower- or uppercase.
                  $ref: '#/components/schemas/postcode'
                city:
                  $ref: '#/components/schemas/city'
                tel:
                  description: A Dutch phone number of 10 digits. Additional dashes and spacing are removed before validating.
                  type: string
                email:
                  type: string
                  format: email
      responses:
        '200':
          description: Basic information of a practice.
          content:
            application/json:
              schema:
                type: object
                properties:
                  practice:
                    type: object
                    properties:
                      name:
                        type: string
                      officialName:
                        type: string
                      practiceAgb:
                        description: The AGB of the practice, if the customer in the response is a practice, otherwise omitted. One of practiceAgb or institutionAgb is always present.
                        $ref: '#/components/schemas/agb'
                      institutionAgb:
                        description: The AGB of the institution, if the customer is a care group or other institute, otherwise omitted. One of practiceAgb or institutionAgb is always present.
                        $ref: '#/components/schemas/agb'
                      gpisMethod:
                        description: The current GPIS type and how medical dossiers are transferred to Zorg op Orde.
                        example: HealthConnected (automatische koppeling)
                      lastImport:
                        $ref: '#/components/schemas/GPIS'
                      doctors:
                        description: AGBs of the doctors working in the practice.
                        type: array
                        items:
                          $ref: '#/components/schemas/doctor'
                      address:
                        type: object
                        properties:
                          address1:
                            type: string
                            description: The first line of the practice postal address (street name and house number, generally).
                            example: Dorpsstraat 1
                          postcode:
                            $ref: '#/components/schemas/postcode'
                          city:
                            $ref: '#/components/schemas/city'
                      contact:
                        type: object
                        properties:
                          tel:
                            type: string
                            example: '0612345678'
                          email:
                            type: string
                            example: M.Dobbelsteen@zorgoporde.nl
                      share_authorizations:
                        description: The GP has granted permission to share certain aspects of the EPD data with the listed third parties.
                        type: array
                        example:
                          - KSYOS_FUNDUS
                        items:
                          type: string
                      dataProcessing:
                        type: object
                        properties:
                          controllers:
                            description: A list of personnel responsible for the data. Usually the practice owner.
                            type: array
                            example:
                              - Mien Dobbelsteen
                              - Lydie van der Ploeg
                            items:
                              type: string
                          agreement:
                            type: object
                            properties:
                              signedBy:
                                description: Full name of the signer.
                                type: string
                                example: Lydie van der Ploeg
                              signedOn:
                                description: Date of signing the data processing agreement.
                                example: 20160501T1344
                                $ref: '#/components/schemas/date'
                    required:
                      - name
                      - officialName
        '400':
          description: If the specified customer is not a practice but some other entity, e.g. a care group.
        '401':
          $ref: '#/components/responses/NoAuth'
        '403':
          description: |-
            User is not allowed to access this API endpoint, or,
            the practice identified by the `agb` parameter does not have a relationship with the
            user (for example, they do not belong to your care group).
  /exports/available:
    get:
      operationId: exportsAvailable
      tags:
        - GPIS exports
      summary: List available exports
      responses:
        '200':
          description: |-
            Lists all available GPIS export snapshots.
            A GPIS export snapshot contains parts of medical dossier info for a subset of all patients in a GP practice. Exactly which filters are applied,
            which data is provided, and how it is formatted is arranged between Zorg op Orde and a party using the ZOO API.
          content:
            application/json:
              schema:
                type: object
                properties:
                  exportSources:
                    type: array
                    items:
                      type: object
                      properties:
                        agb:
                          $ref: '#/components/schemas/agb'
                        name:
                          type: string
                          description: Name of the GP practice
                        available:
                          type: array
                          items:
                            type: object
                            properties:
                              filename:
                                type: string
                                description: This filename can be used in the `/agb/filename` endpoint to fetch this data.
                              timestamp:
                                type: string
                                format: date-time
                                description: |-
                                  The export contains data sourced from an EPD system at this time; it will not
                                  contain any medical dossier data later than this timestamp.
                              tables:
                                type: array
                                description: |-
                                  Lists the names of all tables that are provided as part of this export.<br />
                                  If using the <a href="#tag/Exports/operation/exportsDownload">fetch as zip</a> endpoint, the zip will contain an entry named <code><em>that_name</em>.csv</code>.<br />
                                  If using the <a href="#tag/Exports/operation/exportsDownloadPerTable">fetch each table individually</a> endpoint, this name represents a table name you can ask for.
                                items:
                                  type: string
                            required:
                              - filename
                              - timestamp
                              - tables
                      required:
                        - agb
                        - name
                        - available
        '401':
          $ref: '#/components/responses/NoAuth'
        '403':
          $ref: '#/components/responses/NoAccess'
  /exports/{agb}/{filename}:
    get:
      operationId: exportsDownload
      tags:
        - GPIS exports
      summary: Download an available export
      parameters:
        - name: agb
          in: path
          description: The AGB code of the practice for the export file you want to download.
          required: true
          schema:
            $ref: '#/components/schemas/agb'
        - name: filename
          in: path
          required: true
          description: The name of the file as provided by the `/exports/available` endpoint.
          schema:
            type: string
      responses:
        '200':
          description: |-
            Fetches the requested GPIS export as ZIP file.

            Note that the response will have content type `application/zip` even if the requester's `Accept` header does not indicate this mime type is supported.
        '401':
          $ref: '#/components/responses/NoAuth'
        '403':
          $ref: '#/components/responses/NoAccess'
  /exports/{agb}/{filename}/{tablename}:
    get:
      operationId: exportsDownloadPerTable
      tags:
        - GPIS exports
      summary: Download one CSV table from an available export
      parameters:
        - name: agb
          in: path
          description: The AGB code of the practice for the export file you want to download.
          required: true
          schema:
            $ref: '#/components/schemas/agb'
        - name: filename
          in: path
          required: true
          description: The name of the file as provided by the `/exports/available` endpoint.
          schema:
            type: string
        - name: tablename
          in: path
          required: true
          description: The name of one of the tables in the export as provided by the `/exports/available` endpoint's `tables` list.
          schema:
            type: string
      responses:
        '200':
          description: |-
            Fetches the requested table from the GPIS export.

            Note that the response will have the content type of the request resource (usually `text/csv`) even if the requester's `Accept` header does not indicate this mime type is supported.
        '401':
          $ref: '#/components/responses/NoAuth'
        '403':
          $ref: '#/components/responses/NoAccess'
components:
  parameters:
    Authorization:
      name: Authorization
      in: header
      required: true
      schema:
        type: string
        example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJraWQiOiJaT08tQVBJLVBLSS1JRCIsImFnYiI6IjAxMDEyMzQ1IiwiaWF0IjoxNTE2MjM5MDIyLCJqdGkiOiJ0MTIzNC01Njc4LUFCQ0QifQ.wTesCfFTq1Mz8z7hUWU6zzKSc3dopWnpeETR7eDzFtc
    AgbGP:
      name: agb
      in: query
      description: |-
        The AGB code (dutch: _Algemeen Gegevens Beheer_ - unique identifier for medical professionals and GP practices) of the GP practice.
        This value can be a claim in the JWT (preferred), or, if no `agb` claim exists in the authenticating JWT token, it must be a query parameter.
        The JWT token must be authorized for this entity.
      required: false
      schema:
        $ref: '#/components/schemas/agb'
    AgbCareGroup:
      name: agb
      in: query
      description: |-
        The AGB code (dutch: _Algemeen Gegevens Beheer_ - unique identifier for medical professionals and GP practices) of the entity
        that represents multiple GP practices. This value can be a claim in the JWT (preferred), or, if no `agb` claim exists in the
        authenticating JWT token, it must be a query parameter. The JWT token must be authorized for this entity.
      required: false
      schema:
        $ref: '#/components/schemas/agb'
    Pretty:
      name: pretty
      in: query
      description: If `true` the emitted JSON is pretty-printed. Use only for debugging purposes.
      schema:
        type: boolean
        default: false
    RefDateDefaultToday:
      name: refDate
      in: query
      description: |-
        If present, the date used as context (any measurements available done afterwards aren't taken into account, any expiry calculations
        use this date as reference, and so forth).
        Defaults to today.
      schema:
        $ref: '#/components/schemas/date'
    CareGroup:
      name: group
      in: query
      description: |-
        The 'key' for the care group you want to retrieve data for. Providing this parameter is pointless unless the AGB code supplied
        via the `agb` parameter is responsible for more than one care group which is rare. A list of valid groups can be obtained via
        the `list-groups` endpoint.
      required: false
      schema:
        type: string
    GpCodes:
      name: gpCodes
      in: query
      description: Code of the GP as known in the GPIS.
      example: AA,BZP,RZ,ECH
      schema:
        type: array
        items:
          $ref: '#/components/schemas/Practitioner'
  responses:
    NotAcceptable:
      description: The Accept header as sent by the requestor and the types of content this endpoint can emit have no overlap and thus no response is possible.
    ReqFailure:
      description: The request isn't valid; for example, it is missing a required parameter.
      content:
        application/json:
          schema:
            type: object
            properties:
              errCode:
                description: Some tag from a limited but growing set. Tags will not be removed, only added.
                type: string
                enum:
                  - NO_MED_DATA
              err:
                description: A plain text explanation of what's wrong with the request
                type: string
                example: Either x or y query parameter needs to be present and not blank.
    JwtFailure:
      description: The JWT token isn't valid or wasn't provided.
      content:
        application/json:
          schema:
            type: object
            properties:
              err:
                description: A plain text explanation of what's wrong with the JWT token.
                type: string
                enum:
                  - no JWT included
                  - Unknown signer
                  - Request sent before nfb
                  - Request sent after exp
                  - JWT issued too long ago
                  - Signature missing
                  - Signature invalid
                  - Required claim missing (agb)
                  - Required claim missing (iat)
                  - Required claim missing (kid)
                  - Required claim missing (jti)
                  - JWT already used
    NoAuth:
      description: User is not logged in / session expired.
    NoAccess:
      description: User is not allowed to access this API endpoint.
    PatNotFound:
      description: Provided filter does not match any patients or no medical dossiers are available for this practice.
      content:
        application/json:
          schema:
            type: object
            properties:
              kind:
                description: |-
                  The 'level' of data that isn't available.<br><ul>
                  <li>`patient` indicates that there is medical dossier data available for this GP but the patient that is requested cannot be found.</li>
                  <li>`practice` No medical dossier data is available whatsoever for this practice; either that practice isn't registered or hasn't (yet) provided medical dossier data.</li>
                  </ul>
                type: string
                example: practice
                enum:
                  - practice
                  - patient
    MandateMissing:
      description: Indicated practice is known but has not authorized ZOO to share this information with signer.
  securitySchemes:
    BearerAuth:
      in: header
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |-
        The string "Bearer " followed by a single-use signed JWT token with the mandatory claims as stated in the table below.. The JWT must be signed, preferably with `HS256`.

        <table>
        <tr><th>Claim</th><th colspan="2">Description</th></tr>
        <tr><td>kid</td><td>key id</td><td>A string identifying a trusted signer; agreed upon between user and Zorg op Orde beforehand.</td></tr>
        <tr><td>iat</td><td>Issued at</td><td>Time when this JWT was created and signed. To make up for clock differences, up to five minutes in the future are allowed.</td></tr>
        <tr><td>jti</td><td>Identifier</td><td>A unique string of 10 characters or longer, used to prevent replay. Any given identifier can not be used more than once. As a consequence a JWT can only used once.</td></tr>
        <tr><td>agb</td><td>AGB of the GP</td><td>AGB code (Medical entity identifier), the lookup will be done on the medical dossier data of this practice or entity. The agb may be specified with or without prefix zeros.</td></tr>
        <tr><td>exp</td><td>Expires at</td><td><i>OPTIONAL</i> If included, the request must not be received after this time. May be up to 10 minutes in the future. The difference between the exp claim and the iat must be 20 minutes or less and iat &lt; exp. </td></tr>
        <tr><td>nbf</td><td>Not before</td><td><i>OPTIONAL</i> If included, the request must not be received before this time. Should not be set in the future.</td></tr>
        </table>
  schemas:
    agb:
      type: integer
      minimum: 1
      maximum: 99999999
      example: 1053293
    pat-BSN:
      description: |-
        Patient SSN (dutch: _BSN_). If not known or patient has no BSN, this value will be `0`.

        It is customary that BSNs are 9 digits; this API returns a number, i.e., no leading zeroes.
        API callers may want to transform this value into a string by explicitly left-padding `0`
        characters to the front to make the bsn value 9 digits.
      type: integer
      format: int32
      minimum: 0
      maximum: 999999999
      example: 123456789
    pat-Name:
      description: All relevant info about the patient's name.
      type: object
      properties:
        displayName:
          description: 'The full name as commonly displayed in dutch custom: initials, partner name, followed by own name.'
          type: string
          example: M.A. van der Dussen-de Villepin
        firstName:
          description: |-
            Patient's first name(s), separated by spaces.

            It's possible that no first names are known and instead only initials are known; in that case,
            the initials are provided with dots (`.`) in between the letters, e.g. `"J.M."`.
          type: string
          example: Marie Antoinnette
        initials:
          description: |-
            Patient's initials, with no separators.

            Initials might be derived from a patient's first name if initials weren't explicitly provided by
            the source.
          type: string
          example: MA
        infixOwn:
          description: |-
            The prefix of the patient's own last name (what they were born with; not the name inherited from
            a spouse): `van`, `de`, `van der` - a mostly uniquely dutch aspect to last names.
          type: string
          example: de
          default: ''
        ownLastName:
          description: |-
            The patient's own last name without a prefix (what they were born with; not the name inherited from
            a spouse).
          type: string
          example: Villepin
        infixPartner:
          description: |-
            The prefix of the patient's (ex-)spouse's last name; not all patients that are married go by their
            spouse's last name and often, if they don't, this field will be blank (i.e. not sent).
          type: string
          example: van der
          default: ''
        partnerLastName:
          description: |-
            The the patient's (ex-)spouse's last name without prefix; not all patients that are married go by
            their spouse's last name and often, if they don't, this field will be blank.

            This API does not provide an indication about how this person prefers to be addressed. Culturally it
            is customary for this person to be addressed by their own first name followed by their partner's
            infix and last name if present, and their own if not.
          type: string
          example: Dussen
          default: ''
    gender:
      description: |-
        Patient's gender. `M` = male, `V` = female, `O` = other/unknown.

        Follows [NHG-table-4](https://referentiemodel.nhg.org/sites/default/files/NHG-Tabel%204-Geslacht-versie-5-Inkijkexemplaar_1.pdf).
      type: string
      example: V
      enum:
        - M
        - V
        - O
    date:
      description: Date without time part in ISO-8601 complete extended format.
      type: string
      format: date
      example: '1970-01-13'
    category:
      description: |-
        The status of the patient's registration within this practice.

        As per [NHG-table-5](https://referentiemodel.nhg.org/sites/default/files/NHG-Tabel%205-Categorie%20pati%C3%ABnt-versie-5-Inkijkexemplaar_1.pdf).

        The commonly used status letters are:
        * `V` = Standard patient, part of the GP's population (dutch: _vast_).
        * `T` = Temporary patient (likely do _not_ treat as part of GP's population).
        * `P` = Opportunity patient (dutch: _passant_ - patient is not signed up with this GP. For example: tourist).
      type: string
      example: V
    doctor:
      description: |-
        If known, the AGB code of the primary care GP (dutch: _Inschrijf arts_).

        Value 0 indicates this GPIS or practice doesn't assign patients to individual GPs,
        or this information isn't known.
      type: number
      example: 1051234
    postcode:
      description: The postcode, in `1234AB` format. If not known, blank.
      type: string
      example: 2611PV
    city:
      description: The city or town.
      type: string
      example: Delft
    address:
      description: Patient's address (where they live). If not known, this property will not be in the response.
      type: object
      properties:
        street:
          description: Full name of the street, excluding house number.
          type: string
          example: Lange Geer
        housenumber:
          description: |-
            Just the house number; 0 if unknown or in the exotic case where no house number exists. This does
            not include any addendums such as 'A' or 'room 15'. Guaranteed to be non-negative, and at most 5 digits.
          type: integer
          example: 4
        housenumber_suffix:
          description: |-
            The string that follows the numeric part of the address house number.

            For example, `"A"`, or `"k22"`. Most addresses don't have one.
          type: string
          example: A
          default: ''
        postcode:
          $ref: '#/components/schemas/postcode'
        city:
          $ref: '#/components/schemas/city'
    contact:
      type: object
      properties:
        tel:
          description: |-
            Patient's phone number(s).

            By convention, the mobile number, if available, is always listed first.

            Phone numbers are always in international format (they start with a `+` symbol).
            If no phone numbers are available or patient has no phone, an empty list is returned.
          type: array
          example:
            - '+31612345678'
            - '+31701234567'
          items:
            type: string
        email:
          description: |-
            Patient's email address(es); first one returned is indicated as preferred.

            If no emails are known or available, or patient has no email, an empty list is returned.
          type: array
          items:
            type: string
          example:
            - info@zorgoporde.nl
    insurer-Uzovi:
      description: |-
        Insurer's identity number in the dutch insurance system (dutch: _UZOVI nummer_).

        A value between 0 (no insurance) and 9999; these numbers are customary rendered as 4 digits. When rendering, we suggest callers to left-pad with zeroes.
      type: number
      format: int32
      minimum: 0
      maximum: 9999
      example: 211
    insurance:
      description: |-
        Info about where the patient is insured.

        If patient is not insured, this field will not be present.

        Only the main insurance used for reimbursement of GP costs will be returned, if any such insurance exists.
      type: object
      properties:
        policy_number:
          description: |-
            Patient's insurance registration number (dutch: _polisnummer_).

            In theory can contain alphanumeric characters but no insurer does that as far as we know.

            _if_ the value is fully numeric, any leading zeroes will be stripped.

            We suggest this number is parsed and stored as a string; they can be longer than the limits of
            32-bit/64-bit numbers and therefore exceed JSON's limits on numeric values.
          type: string
          example: 123456789012345
        uzovi:
          $ref: '#/components/schemas/insurer-Uzovi'
    pat-patId:
      description: |-
        _DEPRECATED_ this value will be removed in some future version and you should no longer
        rely on it. Some GPIS use non-numeric public IDs. Use value `patPubId` instead which is like
        this one, except a string instead of a number.

        Patient's "public" ID, as used and shown on the GPIS patient page. Not necessarily unique,
        and not necessarily present; 0 indicates no patid is known or this GPIS does not use (numeric)
        public IDs.

        The primary purpose of this field is to show it to medical professionals working at this practice
        who can use it to search for this dossier and is a way to communicate without sharing privacy-sensitive
        details.

        The number is guaranteed to be positive, and have at most 14 digits. We suggest using a 64-bit numeric
        type to store the number; transferring this number via IEEE-double math (common, in JSON) is safe, as
        the number will not exceed the range within which all whole integers are perfectly representable (~`2^52`).
      type: integer
      format: int64
      example: 1234
    pat-patPubId:
      description: |-
        Patient's "public" ID, as used and shown on the GPIS patient page. Not necessarily unique,
        and not necessarily present; 0 indicates no patid is known or this GPIS does not use public IDs.

        The primary purpose of this field is to show it to medical professionals working at this practice
        who can use it to search for this dossier and is a way to communicate without sharing privacy-sensitive
        details.

        If this isn't present, the value in `patUnid` is the public ID (i.e. there is no difference).
      type: string
      example: P000123
    pat-patUnid:
      description: |-
        Patient's unique and persistent ID in GPIS. Usually identical to `patPubId` but certain GPISes may
        use UUID, or has globally unique keys (e.g. very large numbers). Can be blank, but only
        if supplying GPIS does not send them.
      type: string
      example: '1234'
    endReason:
      description: |-
        Reason patient left the practice (dutch: _reden vertrek_).

        This property is never present if `endDate` isn't present. Otherwise, this value _might_ contain
        a non-blank letter as per [NHG-table-9](https://referentiemodel.nhg.org/sites/default/files/NHG-Tabel%209-Reden%20vertrek-versie-5-Inkijkexemplaar_1.pdf):

        * `A` = To other practice
        * `V` = Moved
        * `O` = died
        * `T` = Temporary
        * `I` = Care home / institution
        * `Q` = unknown
        * `X` = Other
      type: string
      default: ''
    Episode:
      type: object
      required:
        - icpc
        - start
        - mut
      properties:
        icpc:
          description: |-
            The ICPC1.1 (NL variant) code describing this problem / chronic condition.

            Guaranteed to be formatted as `X01.00`, _or_ blank (for GPIS that allow registering problems / conditions without an ICPC).

            Note that certain ICPC1.1 codes are generally stated without the subcode, for example, `B73` (Leukemia). Nevertheless these are
            returned by this API as `B73.00`.
          type: string
          pattern: ^[A-Z]\d{2}\.\d{2}$
          example: A97.00
        start:
          description: |-
            This problem / episode / chronic condition was opened on this date, usually because it was diagnosed on this date.

            Always provided, but may contain the sentinel value of `1900-01-01` if the source doesn't have a start date. Generally
            such episodes are to be treated as having always been part of the patient's dossier.
          $ref: '#/components/schemas/date'
        end:
          description: If the episode has been determined to no longer be relevant (for example, cured), the date when the episode was closed.
          $ref: '#/components/schemas/date'
        mut:
          description: |-
            The last time an event (for example, seeing the patient for chronic care related to this episode) was recorded in context of
            this episode. Is guaranteed to be present and will never be earlier than `start`.
          $ref: '#/components/schemas/date'
        description:
          description: |-
            Most GPIS default the 'description' of an episode to the standard description for the provided ICPC, but allow the
            practitioner to change this description.
          type: string
          example: Geboorte dochter
    Practitioner:
      description: |-
        The medical practitioner (could be a doctor, an assistant, a chronic care specialist working at the GP, etc) who is responsible for entering this
        information. Can be an assistant simply entering data from external sources; necessarily refers to somebody who works for the GP that is the source
        of this medical dossier.

        The format of this string depends on the source. It's sometimes a short 'memo code', sometimes an ID (such as a BIC registry number or AGB code),
        sometimes a full name.

        OPEN QUESTION: Would it be useful if this field is more structured and e.g. explains what it is, or that this field contains an ID that can be
        separately looked up using another API endpoint; we are very dependent on the source for the nature of this information, but some e.g. provide
        the doctor under whose authority a practitioner is operating, which could be useful information. We can't guarantee that we can provide this data
        in a specific structure due to fundamental differences between GPIS vendors, hence why right now this field is free-form.
      type: string
      example: AA
    Measurement:
      type: object
      required:
        - code
        - when
        - value
      properties:
        wcia:
          description: |-
            NHG-standardized WCIA (Werkgroep Coördinatie Informatie Automatisering) code (describes the nature of the measurement),
            as listed on [Webtools NHG labcodeviewer](https://bepalingen.nhg.org/labcodes/determinations), under column 'Nr.'.
          type: number
          example: 1872
        code:
          description: |-
            NHG-standardized labcode (describes the nature of the measurement), as listed on
            [Webtools NHG labcodeviewer](https://bepalingen.nhg.org/labcodes/determinations).
            The full memo+mat+bijz code is provided with no separation.

            If the source allows custom labcodes, this value can contain a non-NHG-standard code. Most source systems do allow this.

            Guaranteed to be provided, and will never be blank.

            OPEN QUESTION: Would it be more convenient if this API guarantees the provided code is NHG compatible, relying on the `source_code` field
            to represent such custom codes?

            OPEN QUESTION: Would it be more convenient if this API provides this code separated out into memo/mat/bijz, e.g. "KREA O MK" instead of "KREAOMK"?
          type: string
          example: KREAOMK
        source_code:
          description: |-
            If the source system uses a different code to represent this measurement in its own system, it is listed here.

            If present, guaranteed to be different from `nhg_code`. For example, a GPIS might use `ROKENHG` instead of NHG-standard `ROOKAQ` to
            represent registration of patient's smoking behaviour.
          type: string
          example: ROKENNHG
        when:
          description: |-
            Date when this measurement was done. In practice it may instead represent the date when the measurement was registered
            which might be a day or two after the measurement was actually performed; not all source systems make it possible to
            distinguish the nature of the date.
          $ref: '#/components/schemas/date'
        value:
          description: |-
            The value of the measurement. Normalized and NHG compatible if possible. For example, enumerated values (such as for `DMHBKZ` which
            represents whether the general practitioner or the specialist is the primary caregiver for chronic diabetes mellitus care) use the
            NHG numeric answer codes (in `DMHBKZ`'s case, `"48"` is returned if the GP is the primary caregiver, and `"49"` if the specialist is).

            If the source provides a value that is not understood by ZOO's normalizers, the source value is provided verbatim.

            This value can be blank; various labcodes simply represent that an act was performed and do not register any result.

            If the value is numeric (for example, systolic blood pressure: `nhg_code = "RRSYKA"`), the dot is used as fractional separator, regardless
            of what the source has provided.
          type: string
          example: 48
        comment:
          description: |-
            Some source systems allow adding a comment to any measurement; if one is present, it is provided here.

            Note that these can be quite lengthy, as sometimes a lab will add standard boilerplate text about how to interpret
            the result in these fields.
          type: string
          example: tekst Sensibilisatie voor algemeen voorkomende inhalatieallergenen (huisstofmijt, kat, hond, graspollen, boompollen, bijvoetpollen, kruidpollen) is op dit moment niet vastgesteld.
        practitioner:
          $ref: '#/components/schemas/Practitioner'
    Feat:
      type: object
      required:
        - vektis
        - when
      properties:
        code:
          description: If present, the source uses a short code (a 'memocode') to represent feats, and this is the code associated with it.
          type: string
          example: ECG
        vektis:
          description: |-
            The vektis code from list 8 (the list for feats GPs can declare) representing this feat.

            For custom feats that therefore cannot actually be declared with any insurance company, this value is 0.
          type: number
          example: 13005
        when:
          description: The stated feat was performed on this date. subscription style feats by convention always on the first day of a quarter.
          $ref: '#/components/schemas/date'
        invoice:
          description: |-
            If this feat has been declared, the invoice id that declared it. Not all source systems track this, and generally
            invoices aren't instantly sent as feats are registered. Thus, if this field isn't provided, either the feat hasn't been invoiced yet,
            or the source system doesn't track invoicing, or the GP office doesn't use the source system for invoicing.
          type: string
          example: A00001234
        gp:
          description: |-
            The GP responsible for this patient at the time of the feat. If income is redistributed to each GP participating in this practice,
            this should be used to know where to send received funds to.

            Contents are free-form as it depends on the source system.
          type: string
          example: AA
        practitioner:
          $ref: '#/components/schemas/Practitioner'
        description:
          description: |-
            Some source systems allow adding a comment or description when registering a feat; often simply a copy of the description of
            what `vektis` represents, but can be explicitly typed in by the practitioner registering this feat.
          type: string
          example: '12001: Dubbel consult huisarts'
    Correspondence:
      type: object
      required:
        - direction
        - when
        - text
      properties:
        direction:
          description: |-
            The direction of the correspondence.
            * `S` means it was sent/initiated from the GP office to `other`.
            * `R` means it was sent/initiated from `other` to the GP office.
            * `X` means the direction isn't known.
          type: string
          example: S
          enum:
            - S
            - R
            - X
        when:
          description: The date when this correspondence was received or sent.
          $ref: '#/components/schemas/date'
        speciality_code:
          description: |-
            A short memocode representing the speciality of `other`. For example, `"OOG"` (eye specialist), `"CHI"` (Surgery), etc. Often blank.

            OPEN QUESTION: Is an explicitly enumerated list of all possible values warranted? We'd love to receive sources of such lists.
          type: string
          example: KNO
        episode:
          description: |-
            An ICPC code (formatted as e.g. `X99.12`) representing the problem or chronic illness that serves as context for this correspondence.

            Not all correspondence can be directly related to an ICPC code, and many source systems fundamentally do not allow linking correspondence to
            a given medical issue. Hence, this field is usually blank.
          type: string
          pattern: ^[A-Z]\d{2}\.\d{2}$
        text:
          description: |-
            The content of the correspondence, as registered in the source system. This usually describes the nature of the content, or is merely a fragment
            of the content, or is simply blank - most source systems do not store a copy of the entire conversation in text form.
          type: string
          example: Echo
        other:
          description: A free-form textual description of the other party in this correspondence.
          type: string
          example: 'Naar: Plastische chirurgie HMC, Den Haag'
        practitioner:
          $ref: '#/components/schemas/Practitioner'
        zorgdomein:
          description: If known and provided, The ZorgDomein message ID. ZorgDomein IDs are often used when referring a patient. Not all source systems provide these.
          type: string
          example: ZD1234
    Medication:
      type: object
      required:
        - atc
      properties:
        atc:
          description: |-
            An [Anatomical Therapeutic Chemical (ATC)](https://en.wikipedia.org/wiki/Anatomical_Therapeutic_Chemical_Classification_System) level 5 code.

            OPEN QUESTION: Is it convenient to also send the dutch and/or english commonly accepted name for this ATC code? Feels wasteful in an API.
          type: string
          format: ^[A-Z]\d{2}[A-Z]{2}\d{2}$
          example: C03CA01
        prescribed:
          description: |-
            If present, the date when a practitioner prescribed this medication; possibly without actual medical review (e.g. just filing a refill request).
            Depending on how the medication was dispensed, some dispensing entities (e.g. pharmacies) are linked with source systems and will cause a
            medication record to be registered that has no prescriber or prescription date (because it wasn't prescribed; at least, not by this GP office),
            but was picked up by the patient.

            We advise coalescing `prescribed` and `delivered`, as this guarantees an actual date.
          $ref: '#/components/schemas/date'
        delivered:
          description: |-
            If present, the date when the patient received this medication (usually, because they picked it up at a pharmacy). Not all pharmacies are
            linked to source systems and therefore, a blank value for `delivered` _may_ mean the prescription was never filled, or it _may_ mean the
            entity that filled the prescription does not relay this to the source system.

            At least one of `prescribed` and `delivered` is guaranteed to have a value.
          $ref: '#/components/schemas/date'
        prescriber:
          $ref: '#/components/schemas/Practitioner'
        end:
          description: |-
            The medication is intended to last the patient no further than this date, if present. If source system doesn't send this date (not all do),
            an estimate based on the nature of the medication and the suggested dosage.

            If not present, this isn't the kind of medication that is designed to be used until symptoms fade or is no longer needed, or,
            our normalization systems aren't capable of normalizing the dosage/form into a meaningful end date.
          $ref: '#/components/schemas/date'
        description:
          description: |-
            This field is usually initialized with a general dutch name for the medication, but can be overwritten with custom text by the prescriber.

            Can describe the general medication or the specific brand name; it varies considerably between source systems.
          type: string
          example: CUTISOFT NWK ST 10X10 48851
        pharmacy:
          description: If automatically sent to a specific pharmacy, some source-system custom coding that indicates which pharmacy it was sent to.
          type: string
          example: AN
        usageCode:
          description: |-
            A coded description of how to use this medication. Depends on source GPIS; sometimes even on the individual configuration of
            a practice's GPIS or that practice's regional server; these values aren't normalized, and sometimes not available at all.
          type: string
          example: 1D1T
        usageText:
          description: Human-readable (dutch) description of how to use this medication. Depends on source GPIS and often not available at all.
          type: string
          example: Gebruik bekend
    Contraindication:
      type: object
      required:
        - description
        - when
      properties:
        description:
          description: |-
            If possible, normalized, but usually a coding unique to the source system or manually typed by a practitioner.

            OPEN QUESTION: Given the unstructured nature of this field, contraindication does not appear usable to callers for anything
            but showing it directly to a practitioner and hoping they know what it means.
          type: string
          example: RAYNAUD, FENOMEEN
        when:
          description: If present, the date when this contraindication was registered.
          $ref: '#/components/schemas/date'
    Journal:
      type: object
      required:
        - when
        - soap
        - text
      properties:
        icpc:
          description: |-
            An ICPC1.1-NL code representing the nature of this journal note. Does not necessarily mean the patient suffers from the condition
            this ICPC represents. For example, a patient that comes in asking questions about signs of Diabetes would have journal text with ICPC `"T90.02"`,
            even if tests show they clearly do not have Diabetes Mellitus.

            Not all journal texts have a context, or a context that can be expressed as an ICPC.
          type: string
          pattern: ^[A-Z]\d{2}.\d{2}$
          example: A97.00
        episode:
          description: |-
            An ICPC1.1-NL code representing the problem / chronic illness that this journal note has been filed under.

            In our experience the difference between `icpc` and `episode` are not well demarkated and practitioners do not necessarily use these fields
            for their intended purpose. We suggest making no distinction between these 2 fields and accepting instead that this means journal text
            can have up to 2 ICPCs associated with them.
          type: string
          pattern: ^[A-Z]\d{2}\.\d{2}$
          example: T90.02
        when:
          description: The date when this journal text was typed and registered.
          $ref: '#/components/schemas/date'
        s:
          description: |-
            The journal text as typed by the practitioner for the 'S' field of SOAP (Subjective / Objective / Analysis / Plan). (Dutch: _S_ / _Subjectief_).

            A (transcription of the) description of the medical issue by the patient themselves.

            Can contain newlines, and can be quite long. For teleconsulting often contains everything the patient typed.
          type: string
        o:
          description: |-
            The journal text as typed by the practitioner for the 'O' field of SOAP (Subjective / Objective / Analysis / Plan). (Dutch: _O_ / _Objectief_).

            The description of the medical issue as observed by a trained medical practitioner.

            Can contain newlines, and can be quite long. For teleconsulting in particular, might be empty.
          type: string
        a:
          description: |-
            The journal text as typed by the practitioner for the 'A' field of SOAP (Subjective / Objective / Analysis / Plan). (Dutch: _E_ / _Evaluatie_).

            The diagnosis.

            Can contain newlines, and can be quite long.
          type: string
        p:
          description: |-
            The journal text as typed by the practitioner for the 'P' field of SOAP (Subjective / Objective / Analysis / Plan). (Dutch: _P_ / _Plan_).

            The course of action to take, or notes about next steps to deal with the issue raised in this journal entry.

            Can contain newlines, and can be quite long.
          type: string
        x:
          description: |-
            The journal text as typed by the practitioner for any non-SOAP field.

            Will be omitted if blank / not available. For source systems that do not work with the SOAP methodology, all journal text will be under this entry.

            Can contain newlines, and can be quite long.
          type: string
        practitioner:
          $ref: '#/components/schemas/Practitioner'
        type:
          description: |-
            A code representing of the style of consult:
            * N - note, generally made without the presence of the patient, for example to register that some lab value was received by mail.
            * C - journal was registered as part of a consult (the patient was present).
            * V - journal was registered during a visit to the patient's location.
            * CT - journal was registered during a phone or other tele-consult.
            * Other codes exist; depends on source system.
          type: string
          example: C
        code:
          description: |-
            If present, a short code representing a specific kind of action, such as a referral (`VER` - from dutch _Verwijzing_),
            `H` for medication recipe refill (dutch: _Herhaalrecept_), `REC` for prescribing a recipe, `LAB` for processing laboratory results,
            or `BVO` for a nationally organized checkup such as for Cervical Cancer (from dutch: _Bevolkingsonderzoek_).

            This coding depends on the source system, and not all source systems use this concept (if the source is such a system, this field is never present),
            nor do they use standardized codes for this concept.
          type: string
          example: REC
    careprograms:
      type: object
      properties:
        principal:
          description: |-
            A list of keys (strings) describing which care programs this patient
            is actively receiving (they have been diagnosed or marked for inclusion in
            the program, _and_ they are marked as receiving this care via the GP (not a specialist),
            _and_ they are marked as being actively enrolled in a chronic care program for it).

            A program is considered _principal_ (in contrast to _auxiliary_) if no other program
            the patient is actively participating in supersedes it (even partially).

            The list of possible care program values can change; we advise treating this value as
            a plain string and not an enum hardcoded in your codebase.

            Note that careprogram inclusion depends on a GP practice's processes; if Zorg op Orde
            has not been informed about these, no care programs will be reported.

            Currently, the set of possible values is
              - dm
              - copd
              - astma
              - hvz
              - vvr
              - ouderenzorg
              - atriumfibrilleren
              - hartfalen
              - dermatoscopie
              - fractuurpreventie
              - ecg
          type: array
          items:
            type: string
          example:
            - dm
            - copd
        auxiliary:
          description: |-
            Just like _principal_, except, all programs listed here are incompletely applied
            because another program the patient participates in covers some or all of the care
            implied by this program, and this program is treated as the auxiliary one.
          type: array
          items:
            type: string
          example:
            - vvr
    displayName:
      description: 'The full name as commonly displayed in dutch custom: initials, partner name, followed by own name.'
      type: string
      example: M.A. van der Dussen-de Villepin
    tel:
      description: |-
        Patient's phone number(s).

        By convention, the mobile number, if available, is always listed first.

        Phone numbers are always in international format (they start with a `+` symbol).
        If no phone numbers are available or patient has no phone, an empty list is returned.
      type: array
      example:
        - '+31612345678'
        - '+31701234567'
      items:
        type: string
    email:
      description: |-
        Patient's email address(es); first one returned is indicated as preferred.

        If no emails are known or available, or patient has no email, an empty list is returned.
      type: array
      items:
        type: string
      example:
        - info@zorgoporde.nl
    TermsDictionary:
      description: |-
        Provides definitions of codes used in the rest of this response. Only codes used in the response messages are added to the dictionary. For example: if the response doesn't enclose measurements, then these are not in the dictionary. If the response holds feat codes 12001 and 12004, but not 12011, then the dictionary holds 12001 and 12004, but not 12011.

        Always sent first.
      type: object
      properties:
        measurements:
          description: |-
            Represents measurements (such as bloodpressure) and snapshot determinations (such as 'who is responsible for Type 2 diabetes chronic care'),
            based on NHG memocodes. Each key in this object is a full NHG memocode (with no spaces), and each value is an object. That object
            contains a key/value pair `"num"` containing the NHG numeric code for that memocode, a k/v pair `"text"` containing a dutch human
            readable description. If the valid values for this measurement are enumerated, a k/v pair `"nhgVal": true` is present. That means the
            value of such a measurement can be looked up in the `nhgAnswers` entry.
          type: object
          additionalProperties: true
          example:
            DMHBTZ:
              num: 2206
              text: hoofdbehandelaar diabetes
              nhgVal: true
        nhgAnswers:
          description: 'Enumerated NHG answers (the answer to any measurements with `"nhgVal": true`) can be looked up here.'
          type: object
          additionalProperties: true
          example:
            '48': Huisarts
            '49': Specialist
        icpcs:
          description: |-
            Represents diagnoses and medical conditions, based on the ICPC1.1-NL standard. Keys in this object represent ICPC codes, always
            formatted as a capital letter, followed by 2 digits, a dot, and 2 more digits. These map to value objects that contain 2
            k/v pairs: `"text"` which contains dutch human readable text explaining what this ICPC code represents, and a `"classText"` k/v pair
            containing the dutch human readable name of the class (the letter).
          type: object
          additionalProperties: true
          example:
            T90.02:
              text: Diabetes mellitus type 2
              classText: Endocriene klieren/metabol./voeding
        atcs:
          description: |-
            Represents medications, mapping ATC codes to value objects containing one k/v pair: `"text"` to a dutch human readable
            description of the medication. The ATC codes may represent groups of medications (less than 7 characters).
          type: object
          additionalProperties: true
          example:
            A02AB:
              text: Aluminiumverbindingen
            A11GA01:
              text: Ascorbinezuur
        feats:
          description: Vektis COD367 list 8 feat codes. The code list may change over time. The codes described here match with those used in the response.
          type: object
          additionalProperties: true
          example:
            '12001':
              text: Consult regulier 20 minuten en langer
            '12904':
              text: Materiaalkosten teststrips bloedsuikerbepaling diabetespatiënten (waaronder eyetone-teststrips)
            '99999':
              text: Onbekende verrichting
    gpisType:
      type: string
      description: Type brand (or type) of the general practitioner information system (EDP). Query the `/customer/gpisType` end point for a list of all brands.
      enum:
        - healthconnected
        - medicom
        - scipio
        - microhis
        - promedico
        - tetra
        - sanday
        - microhis
        - medikit
    dateTime:
      description: Timestamp in complete basic representation of date and time according ISO 8601.
      type: string
      format: datetime
      example: 19700131T235901
    GPIS:
      description: 'The source of the medical data used to produce this report: which general practitioner information system was used, and when the data was provided. Omitted if no GPIS database was imported (yet).'
      type: object
      properties:
        gpisType:
          $ref: '#/components/schemas/gpisType'
        timestamp:
          description: |-
            The report is based on dossier data as it was on this timestamp; due to inaccuracies by GP information systems that source the data,
            this value is not always accurate and can be off by as much as a week.
          $ref: '#/components/schemas/dateTime'
    fundus-status:
      type: object
      required:
        - agb
        - name
        - gpis
        - refDate
        - patients
      properties:
        agb:
          description: The AGB code of the GP practice whose patients are provided in this object.
          $ref: '#/components/schemas/agb'
        name:
          description: A human readable name describing the GP practice (The entity whose AGB code is sent as `agb`).
          type: string
        gpis:
          $ref: '#/components/schemas/GPIS'
        refDate:
          $ref: '#/components/schemas/date'
          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. The date depends on the last time the EPD system provided
            data; generally it will be quite recent.
            example: '2024-04-01'
        patients:
          type: array
          items:
            type: object
            description: |-
              Which patients are returned, and which Personal Identifying Information properties are sent
              depends on the chosen `purpose` when making this API call.
            required:
              - patid
              - patUnid
              - doctor
              - category
              - fundus
            properties:
              bsn:
                $ref: '#/components/schemas/pat-BSN'
              name:
                $ref: '#/components/schemas/pat-Name'
              gender:
                $ref: '#/components/schemas/gender'
              dob:
                $ref: '#/components/schemas/date'
              category:
                $ref: '#/components/schemas/category'
              doctor:
                $ref: '#/components/schemas/doctor'
              address:
                $ref: '#/components/schemas/address'
              contact:
                $ref: '#/components/schemas/contact'
              insurance:
                $ref: '#/components/schemas/insurance'
              patid:
                $ref: '#/components/schemas/pat-patId'
              patPubId:
                $ref: '#/components/schemas/pat-patPubId'
              patUnid:
                $ref: '#/components/schemas/pat-patUnid'
              startDate:
                $ref: '#/components/schemas/date'
              endDate:
                $ref: '#/components/schemas/date'
              endReason:
                $ref: '#/components/schemas/endReason'
              fundus:
                type: object
                required:
                  - careprogram
                  - director
                  - lastEval
                  - retinoVal
                  - left
                  - right
                properties:
                  careprogram:
                    description: The care program that is the primary reason Funduscopy status is applicable to this patient.
                    type: string
                    example: Ouderenzorg
                  director:
                    type: object
                    description: 'Contains info about the funduscopy director: Who is responsible for this patient''s funduscopy care and followup?'
                    required:
                      - source
                      - nhgResult
                    properties:
                      source:
                        description: |-
                          The aspect of the medical dossier used to determine who is director. Usually one of:
                          * `DMRFTZ` – indicates that NHG-standard lab/measurement registration 'Regie funduscopie' is used.
                          * `implied` – Nothing explicit is available in the medical dossier, and the default as per the policies of this care group is provided.
                        type: string
                        example: DMRFTZ
                      timestamp:
                        type: string
                        format: date
                        description: |-
                          If present, the medical dossier entry used to conclude the funduscopy director was measured/entered on this date.
                          For example, if `DMRFTZ` registration is used, the date of that measurement as per the dossier.
                      nhgResult:
                        description: |-
                          The director, in NHG answercode for `DMRFTZ` form, regardless of what `source` actually provided this result:
                          * `48` - The GP is responsible for managing funduscopy
                          * `49` - The specialist is responsible
                          * `212` - Unknown
                        type: integer
                        format: int32
                        enum:
                          - 48
                          - 49
                          - 212
                  lastEval:
                    description: |-
                      The date of the last time the patient has received Funduscopy; will be `null` if no funduscopy is registered.

                      The most recent measurement date is provided, even if only one eye was measured on that date.
                    $ref: '#/components/schemas/date'
                  retinoVal:
                    description: |-
                      The normalized retinopathy category for the worst eye, in terms of the 2017 Retinopathy level standard (richtlijn Diabetische Retinopathie 2017).

                      * `-1` – retinopathy level is unknown or cannot be determined.
                      * `0` – Retinopathy level R0: No visible retinopathy.
                      * `1` - Retinopathy level R1: Mild background retinopathy.
                      * `2` - Retinopathy level R2: Pre-proliferative retinopathy.
                      * `3` - Retinopathy level R3: Proliferative retinopathy.
                    type: integer
                    format: int32
                    minimum: -1
                    maximum: 3
                  left:
                    description: Details about specifically the left eye.
                    type: object
                    required:
                      - lastEval
                      - retinoVal
                    properties:
                      lastEval:
                        description: Same as previous level, specifically for left eye.
                        $ref: '#/components/schemas/date'
                      retinoVal:
                        description: Same as previous level, specifically for left eye.
                        type: integer
                        format: int32
                        minimum: -1
                        maximum: 3
                      note:
                        description: |-
                          If present, describes why this measurement is missing, unclear, or suboptimal.

                          For example, might mention that the result from the lab is likely available, but has not
                          been properly registered in the medical dossier, or that a result is available but only after
                          the provided `refDate`. In dutch, and human readable.
                        type: string
                      nhgCode:
                        description: If present, the NHG memocode used to register the retinopathy level. Will be in the terms dictionary.
                        type: string
                        example: DMR7FALI
                      nhgResult:
                        description: If present, the NHG result value describing the retinopathy level. Will be in the terms dictionary.
                        type: integer
                        format: int32
                        example: 562
                  right:
                    type: object
                    description: Like the left eye.
                    required:
                      - lastEval
                      - retinoVal
                    properties:
                      lastEval:
                        $ref: '#/components/schemas/date'
                      retinoVal:
                        type: integer
                        format: int32
                        minimum: -1
                        maximum: 3
                      note:
                        type: string
                      nhgCode:
                        type: string
                      nhgResult:
                        type: integer
                        format: int32
                  followup:
                    type: object
                    description: Contains information about advice given to patient about scheduling future fundus inspections (aka fundus followup).
                    properties:
                      nhgResult:
                        description: |-
                          The followup advice, in NHG answercode for `FSFUFZ` form, regardless of how this followup advice was registered:
                          * `326` – within 1 day with a specialist
                          * `325` – within 1 week with a specialist.
                          * `324` – within 1 month with a specialist.
                          * `323` – within 3 months with a specialist.
                          * `566` – within 6 months with a specialist.
                          * `322` – regular scheduling at 1 year frequency.
                          * `386` – regular scheduling at 2 year frequency.
                          * `565` – regular scheduling at 1 year frequency.
                          * `619` – No fundus checkup required.
                        type: integer
                        format: int32
                        enum:
                          - 326
                          - 325
                          - 324
                          - 323
                          - 566
                          - 322
                          - 386
                          - 565
                          - 619
                      nhgCode:
                        description: If present, the NHG memocode used to register the followup advice. Will be in the terms dictionary.
                        type: string
                        example: FSFUFZ
                      timestamp:
                        $ref: '#/components/schemas/date'
                        description: Date when this followup advice was registered.
                      before:
                        $ref: '#/components/schemas/date'
                        description: |-
                          The fundus followup advice indicates fundus needs to be done at or before this date.

                          Determined by taking the last time fundus checkup was performed based on e.g. a `DMR7FALI` measurement, and adding the followup advice time
                          to that date. If no fundus inspection has been done yet, the date at which the followup advice was given, plus the time indicated in the followup
                          advice, is provided (e.g. if on April 5th the followup advice is 'within one month', this value will be 'May 5th').

                          Will be the sentinel value 'Jan 1st, 9999' if no followup advice is needed.
    employee-alias:
      description: Alias for the doctor, sometimes called _memocode_. Should be an unique identifier for a doctor in a GPIS.
      type: string
      example: MH,RZ,AXW
    FeatCode:
      description: Vektis COD367 list 8 feat code expressed as an integer.
      type: integer
    CareProgram-enum:
      description: |-
        The kind of chronic care that this care program caters to.
        _WARNING_: HVZ and VVR are being debated; this really is a single care program (probably called CVRM). This may change soon.

        _NOTE_: This list is expanded any time new care programs are introduced. API callers are encouraged not to hardcode the list
        of enumerated values, or at least be prepared to accept other values.

        <dl>
        <dt>DM</dt><dd>Diabetes Mellitus; generally only Type 2</dd>
        <dt>COPD</dt><dd>Chronic Obstructive Pulmonary Disease</dd>
        <dt>Astma</dt><dd>Astma</dd>
        <dt>HVZ</dt><dd>Cardiovascular Risk Management (CVRM) - Primary chronic care (more serious than VVR).</dd>
        <dt>VVR</dt><dd>Cardiovascular Risk Management (CVRM) - Secondary chronic care (less serious than HVZ).</dd>
        <dt>OuderenZorg</dt><dd>Elderly care</dd>
        <dt>AtriumFibrilleren</dt><dd>Atrial fibrillation - often part of the CVRM group of chronic care.</dd>
        <dt>Hartfalen</dt><dd>(Congestive) Heart Failure - often part of the CVRM group of chronic care.</dd>
        <dt>Dermatoscopie</dt><dd>Dermatoscopy / (risk of) skin cancer</dd>
        <dt>FractuurPreventie</dt><dd>Fracture prevention - often part of elderly care.</dd>
        <dt>GecMonitoring</dt><dd>An assortment of indicators useful for monitoring a GEC (Geïntegreerd Eerstelijns Centrum / integrated primary care).</dd>
        <dt>Nierschade</dt><dd>(risk of) kidney failure</dd>
        </dl>
      type: string
      example: COPD
    Indicator:
      type: object
      required:
        - key
        - title
        - type
        - style
        - bars
      properties:
        key:
          description: Unique identifier, not to be shown to the user, for referring to this indicator in other API calls
          type: string
          example: ZEL-dm2-bp-result
        basedOn:
          description: |-
            *OPTIONAL* Refers to the key of another indicator in this set; the data this indicator represents is a calculation
            based on the population of the referred-to indicator. Not necessarily something that needs to be shown in the user interface.
          type: string
          example: ZEL-dm2-bp
        title:
          description: Short, in dutch, plain text.
          type: string
          example: Prevalentie Diabetes
        focus:
          description: |-
            Caregroups can choose key performance indicators; such indicators are considered 'focus' indicators.
            Focus indicators tend to be temporary; most caregroups adjust them yearly or every other year.
          type: boolean
          example: false
        htmlDescription:
          description: In dutch, HTML formatted; if present, contains details on how this value is measured (in more readable, less technical terms than `htmlDetail`.
          type: string
          example: Patiënten met ≥ 1 voorschrift(en) long acting beta-2 agonists (LABA) of long acting muscarine antagonists (LAMA) in de afgelopen 12 maanden
        htmlDetail:
          description: In dutch, HTML formatted; if present, contains specific details on how this value is measured (for example, contains information about which NHG bepaling codes are used).
          type: string
          example: LAMA (<code>R03BB</code> (04, 05, 06 of 07)) of LABA (<code>R03AC</code> (12, 13, 18 of 19))
        type:
          description: |-
            What kind of indicator this is.

            `basic` and `goal` are roughly the same: They represent the measurement/registration status of a certain medical aspect, such as blood pressure, and always
            break down in 3 groups: "Patients for whom this measurement/registration has been performed", "same, but in a way that cannot be parsed or isn't the preferred registration/measurement method", "not measured/registered". A `goal` type also has a goal of some sort (a minimum % of patients for which this property needs to be measured/registered, for example to meet care group aims or a goal stipulated by
            a national standard or insurance negotiation). A `basic` type doesn't have such a goal.

            `prevalence` is somewhat special: It measures how many patients are relevant for the care this indicatorset is about.

            `result` represents the patients for whom a certain medical aspect is registered/measured, divided into categories. For example, for bloodpressure, all those patients with a valid, standardized
            blood pressure measurement are sorted into "their blood pressure is allright", "their blood pressure is a bit high", and "they suffer from high blood pressure". result type indicators have
            legends.
          type: string
          example: basic
          enum:
            - basic
            - goal
            - prevalence
            - result
        index:
          description: |-
            *OPTIONAL* Indicators usually are based on documentation that tends to take the form of an
            ordered list (like html `<ol>`), and it is convenient for indicators to copy this numbering scheme.
            For most UI applications, simply prefix this to the title, e.g. render as `1. Title Here`.
            If missing, do not show an index in the title.
          type: integer
          format: int32
          minimum: 1
          example: 1
        xMin:
          description: |-
            Numeric value of the far left of the bar; represents a ratio (0.0-1.0).
            Most indicators range from 0% to 100%, but for some, where the values to be shown represent only a small percentage,
            the bar is 'zoomed in'; it represents only a slice of the total range.
          type: number
          example: 0.05
          default: 0
        xMax:
          description: |-
            Numeric value of the far right of the bar; represents a ratio (0.0-1.0).
            Most indicators range from 0% to 100%, but for some, where the values to be shown represent only a small percentage,
            the bar is 'zoomed in'; it represents only a slice of the total range. Generally, `prevalence` type indicators have an `xMax` that isn't 1.0.
          type: number
          example: 0.105
          default: 1
        markers:
          description: |-
            A marker is rendered on the percentage bar and represents a noteworthy boundary, for example, for a prevalence indicator,
            one standard deviation up, respectively down, from the average, to provide context. Or, a goal as set forth by a zorggroep
            or national standards body e.g. for how many diabetes patients should have a recent HbA1c measurement. If the indicator itself
            is shown as a horizontal bar, this would be a small vertical line rendered on top of it. Generally, `prevalence` and `goal` type indicators have markers.
          type: array
          items:
            type: number
          example:
            - 0.25
            - 0.8
        unitDesc:
          description: '*OPTIONAL* describes the unit that the stated legend values are in, in dutch, and *HTML*. For example, if showing blood pressure, `mmHg`. If missing, treat as the empty string (do not show unit at all).'
          type: string
          example: mmHg
          default: ''
        style:
          description: |-
            A key that describes the render style for this entire indicator.
            For example, 'failed' indicates that the indicator should be rendered
            with a red hue to focus the user's attention on the fact that this
            indicator represents a goal or requirement that they do not currently
            meet.
          type: string
          example: failed
          default: normal
          enum:
            - normal
            - pass
            - fail
        counts:
          description: '*OPTIONAL* If present, the actual values (i.e. number of patients) for each segment of the main bar; if the bar is not complete (the values do not add up to 100), an extra value is included representing this remainder.'
          type: array
          items:
            type: number
          example:
            - 11
            - 157
            - 0
            - 2
        legend:
          description: '*OPTIONAL* If present, render a legend box with the card explaining what each kind of segment (see `bars > segments`) represents. Each item in this array maps maps a style (as used in `bars > segments > style`) onto a very short, dutch, *HTML* description. Generally only `result` type indicators have a `legend`.'
          type: array
          items:
            type: object
            properties:
              title:
                description: The short, human readable description (dutch, *HTML*).
                type: string
              category:
                description: A key indicating which style to apply this segment / legend.
                type: string
                enum:
                  - preferred
                  - alternative
                  - negative
                  - regProblem
                  - red
                  - orange
                  - high
                  - good
                  - low
                  - 'yes'
                  - await
                  - 'no'
                  - late
                  - concern
                  - mild
                  - serious
              value:
                description: The amount of patients in this segment for the main bar.
                type: number
          example: |-
            [
              {
                "title": "≥140",
                "category": "serious",
                "value": 11
              },
              {
                "title": "120-140",
                "category": "concern",
                "value" 50
              },
              {
                "title": "≤120",
                "category": "good",
                "value": 60
              }
            ]
        bars:
          type: array
          items:
            description: |-
              Each bar describes the calculated result for one entity at one measurement date. For example, an indicator box could contain 3 such entries:
              * The practice, this quarter. * The practice, previous quarter (to put this quarter into context). * GP group (<em>zorg groep</em>)'s results this quarter.
              There is always at least one. The first one is the main bar, that is, what this report is reporting on; all further bars exist solely to provide context.
            type: object
            required:
              - segments
            properties:
              calculated:
                description: The timestamp on which the bar was calculated. This can be different from the reference date. Mainly for debugging purposes.
                $ref: '#/components/schemas/dateTime'
              legend:
                description: |-
                  *OPTIONAL* A short *HTML* (dutch) description of the entity+measurement date represented by this bar.
                  If only one bar is provided, can be missing (no legend is needed).
                type: string
                example: Praktijk 2023Q3
                default: ''
              pop:
                description: |-
                  A number representing the total population that this indicator has calculated against; can have decimal values if this
                  indicatorset represents a group average.
                type: number
                example: 854
              segments:
                type: array
                items:
                  description: |-
                    Each segment represents a slice of the measured population. For example, those patients in the diabetes care program with a recent blood pressure measurement registration, or, for an indicator showing the distribution of blood pressure values amongst those with a recent registration, the number of patients whose BP measurement is of serious health concern.
                    Place each segment in sequence in the bar. They are guaranteed to fit. The values for each part are relative to `xMin`/`xMax`, e.g. a percentage. They may not add up to 100 - in that case, leave the remainder blank.
                    For example:
                    * 3 segments for 'blood pressure results': 40-Good, 35-Concern, 25-Problematic. * 1 segment for 'blood pressure has been measured': 85-Measured
                  type: object
                  required:
                    - style
                    - value
                  properties:
                    style:
                      description: |-
                        Describes what kind of ratio this segment describes.
                        Each segment represents some kind of ratio and this describes the nature of it. Render the segment according to its style. For example, `serious` (indicating a group of patients whose lab result for this indicator is of serious concern, i.e. medically speaking quite bad news) could be rendered dark red. Same categories as `legend` - `category`
                      type: string
                      example: concern
                    value:
                      description: |-
                        The value (in percent). For example, if `xMin` is .10, `xMax` is .40, and this is .20, render this segment at 33% of
                        the total length (because .20 is a third of the way in, in the range .10-.40).
                      type: number
                      example: 0.2972
    IndicatorSet:
      description: 'A report about a care program based on showing a number of ratios, such as: "How many people in your practice have diabetes?", or: "For all diabetes patients in your care with a recent blood pressure measurement, how do these blood pressure measurements split into problematic / concern / okay categories?"'
      type: object
      required:
        - key
        - name
        - refDate
        - calculating
      properties:
        gpis:
          $ref: '#/components/schemas/GPIS'
        key:
          description: Unique identifier, not to be shown to the user, for referring to this indicator set in other API calls
          type: string
          example: ZOO-dm
        name:
          description: Human readable dutch text; should fit in one line.
          type: string
          example: Diabetes Mellitus type 2 – per InEen 2023 accreditatie
        careprogram:
          $ref: '#/components/schemas/CareProgram-enum'
        refDate:
          description: Reference date for which the indicators are calculated on the population (peildatum).
          $ref: '#/components/schemas/date'
        calculating:
          description: |-
            Calculating an indicator set report takes some time; this API responds with a `calculating` value of less than 1.0 and
            no `chapters` section (thus, no data). Call this endpoint a few times to get status updates. Once calculation is complete,
            `1.0` will be returned and `chapters` will be provided.
          format: number
          minimum: 0
          maximum: 1
        bars:
          description: Describes the bars in the indicators used in the indicatorGroups.
          type: array
          items:
            type: object
            properties:
              calculated:
                type: object
                properties:
                  from:
                    description: Timestamp of the oldest indicator calculation in the set.
                    $ref: '#/components/schemas/dateTime'
                  to:
                    description: Timestamp of the newest indicator calculation in the set.
                    $ref: '#/components/schemas/dateTime'
              population:
                type: object
                properties:
                  entity:
                    type: string
                    enum:
                      - gp
                      - tag
                  tag:
                    description: The name of a care group or other population, but never a practice.
                    type: string
                  unid:
                    description: For internal use by Zoo.
                    type: integer
                  snapshotId:
                    description: For internal use by Zoo.
                    type: integer
              refDate:
                description: Reference date for which the indicators are calculated on the population.
                $ref: '#/components/schemas/dateTime'
              title:
                description: Title for use in the GUI as a legend for bar.
                type: string
        chapters:
          description: Each chapter has a title and contains 1 or more indicators.
          type: array
          items:
            type: object
            required:
              - title
              - indicatorGroups
            properties:
              title:
                description: In dutch, plain text formatted; should fit on one line.
                type: string
                example: Populatie
              indicatorGroups:
                description: |-
                  A chapter contains 1 or more indicator groups. An indicator group is an array of indicators which should
                  always be shown together; they are each other's context. These arrays are never empty, but often contain
                  just one indicator. It is extremely rare for such a set to contain more than 2.
                type: array
                items:
                  type: array
                  items:
                    $ref: '#/components/schemas/Indicator'
        cache:
          description: If true, the indicator set was retrieved from the API cache. The set is only retrieved from the cache if there is no recent calculation available in the database and if the set won't change anymore. This is the case for all indicator sets which were calculated with a reference date in the past and for which a certain period no new GPIS-data is provided. The cached indicator set reflects the indicator definitions of the reference date. Cached indicators are not updated with new definitions.
          type: boolean
    key:
      description: Unique identifier, not to be shown to the user, for referring to this indicator in other API calls
      type: string
      example: ZEL-dm2-bp-result
    title:
      description: Short, in dutch, plain text.
      type: string
      example: Prevalentie Diabetes
    type:
      description: |-
        What kind of indicator this is.

        `basic` and `goal` are roughly the same: They represent the measurement/registration status of a certain medical aspect, such as blood pressure, and always
        break down in 3 groups: "Patients for whom this measurement/registration has been performed", "same, but in a way that cannot be parsed or isn't the preferred registration/measurement method", "not measured/registered". A `goal` type also has a goal of some sort (a minimum % of patients for which this property needs to be measured/registered, for example to meet care group aims or a goal stipulated by
        a national standard or insurance negotiation). A `basic` type doesn't have such a goal.

        `prevalence` is somewhat special: It measures how many patients are relevant for the care this indicatorset is about.

        `result` represents the patients for whom a certain medical aspect is registered/measured, divided into categories. For example, for bloodpressure, all those patients with a valid, standardized
        blood pressure measurement are sorted into "their blood pressure is allright", "their blood pressure is a bit high", and "they suffer from high blood pressure". result type indicators have
        legends.
      type: string
      example: basic
      enum:
        - basic
        - goal
        - prevalence
        - result
    htmlDescription:
      description: In dutch, HTML formatted; if present, contains details on how this value is measured (in more readable, less technical terms than `htmlDetail`.
      type: string
      example: Patiënten met ≥ 1 voorschrift(en) long acting beta-2 agonists (LABA) of long acting muscarine antagonists (LAMA) in de afgelopen 12 maanden
    htmlDetail:
      description: In dutch, HTML formatted; if present, contains specific details on how this value is measured (for example, contains information about which NHG bepaling codes are used).
      type: string
      example: LAMA (<code>R03BB</code> (04, 05, 06 of 07)) of LABA (<code>R03AC</code> (12, 13, 18 of 19))
    focus:
      description: |-
        Caregroups can choose key performance indicators; such indicators are considered 'focus' indicators.
        Focus indicators tend to be temporary; most caregroups adjust them yearly or every other year.
      type: boolean
      example: false
    IndicatorDetail:
      description: A report about a specific aspect of a care program, listing how each patient is categorized.
      type: object
      properties:
        dict:
          $ref: '#/components/schemas/TermsDictionary'
        gpis:
          $ref: '#/components/schemas/GPIS'
        key:
          $ref: '#/components/schemas/key'
        title:
          $ref: '#/components/schemas/title'
        type:
          $ref: '#/components/schemas/type'
        refDate:
          $ref: '#/components/schemas/date'
        htmlDescription:
          $ref: '#/components/schemas/htmlDescription'
        htmlDescriptionDetail:
          $ref: '#/components/schemas/htmlDetail'
        focus:
          $ref: '#/components/schemas/focus'
        blocks:
          description: A block describes one particular outcome (such as 'patients with conflicting registration').
          type: array
          items:
            type: object
            required:
              - title
              - patients
            properties:
              title:
                description: Describes the nature of what this block of patients represents. *HTML*.
                type: string
                example: Hoofdbehandelaar is geregistreerd als 'Onbekend'
              description:
                description: '*OPTIONAL* Additional information about this block of patients; usually instructions about recommended medical / GP actions. *HTML*.'
                type: string
                example: |-
                  Voor deze patiënten hebben we geen registratie van de hoofdbehandelaar kunnen vinden in de uit uw HIS aangeboden informatie.<br />
                  We raden u om deze lijst door te nemen en de hoofdbehandelaar te registreren.
              patients:
                description: A list of all patients in this block with details about why they are in this block.
                type: array
                items:
                  type: object
                  properties:
                    patUnid:
                      $ref: '#/components/schemas/pat-patUnid'
                    bsn:
                      $ref: '#/components/schemas/pat-BSN'
                    name:
                      $ref: '#/components/schemas/pat-Name'
                    dob:
                      $ref: '#/components/schemas/date'
                    expl:
                      description: An explanation of why this patient is in this block, in medmark format.
                      type: string
                      example: '[NHG DMHB TZ] = [NHGA 49] op [DATE 20220223].'
                  required:
                    - patUnid
                    - bsn
                    - name
                    - dob
                    - expl
      required:
        - gpis
        - key
        - name
        - refDate
        - description
        - blocks
    xMin:
      description: |-
        Numeric value of the far left of the bar; represents a ratio (0.0-1.0).
        Most indicators range from 0% to 100%, but for some, where the values to be shown represent only a small percentage,
        the bar is 'zoomed in'; it represents only a slice of the total range.
      type: number
      example: 0.05
      default: 0
    xMax:
      description: |-
        Numeric value of the far right of the bar; represents a ratio (0.0-1.0).
        Most indicators range from 0% to 100%, but for some, where the values to be shown represent only a small percentage,
        the bar is 'zoomed in'; it represents only a slice of the total range. Generally, `prevalence` type indicators have an `xMax` that isn't 1.0.
      type: number
      example: 0.105
      default: 1
    markers:
      description: |-
        A marker is rendered on the percentage bar and represents a noteworthy boundary, for example, for a prevalence indicator,
        one standard deviation up, respectively down, from the average, to provide context. Or, a goal as set forth by a zorggroep
        or national standards body e.g. for how many diabetes patients should have a recent HbA1c measurement. If the indicator itself
        is shown as a horizontal bar, this would be a small vertical line rendered on top of it. Generally, `prevalence` and `goal` type indicators have markers.
      type: array
      items:
        type: number
      example:
        - 0.25
        - 0.8
    unitDesc:
      description: '*OPTIONAL* describes the unit that the stated legend values are in, in dutch, and *HTML*. For example, if showing blood pressure, `mmHg`. If missing, treat as the empty string (do not show unit at all).'
      type: string
      example: mmHg
      default: ''
    legend:
      description: '*OPTIONAL* If present, render a legend box with the card explaining what each kind of segment (see `bars > segments`) represents. Each item in this array maps maps a style (as used in `bars > segments > style`) onto a very short, dutch, *HTML* description. Generally only `result` type indicators have a `legend`.'
      type: array
      items:
        type: object
        properties:
          title:
            description: The short, human readable description (dutch, *HTML*).
            type: string
          category:
            description: A key indicating which style to apply this segment / legend.
            type: string
            enum:
              - preferred
              - alternative
              - negative
              - regProblem
              - red
              - orange
              - high
              - good
              - low
              - 'yes'
              - await
              - 'no'
              - late
              - concern
              - mild
              - serious
          value:
            description: The amount of patients in this segment for the main bar.
            type: number
      example: |-
        [
          {
            "title": "≥140",
            "category": "serious",
            "value": 11
          },
          {
            "title": "120-140",
            "category": "concern",
            "value" 50
          },
          {
            "title": "≤120",
            "category": "good",
            "value": 60
          }
        ]
    name:
      description: Name of the GP practice
      type: string
    properties-agb:
      description: AGB of the GP practice, if known.
      type: integer
      format: int32
      minimum: 1
      maximum: 99999999
    IndicatorParticipants:
      description: A report about a specific aspect of a care program, listing the stats of each participating GP practice.
      type: object
      properties:
        group:
          description: The chosen group (repeats `group` parameter if present, otherwise, the group defaulted to for authenticating user).
          type: string
          example: hwf
        key:
          $ref: '#/components/schemas/key'
        title:
          $ref: '#/components/schemas/title'
        type:
          $ref: '#/components/schemas/type'
        refDate:
          $ref: '#/components/schemas/date'
        htmlDescription:
          $ref: '#/components/schemas/htmlDescription'
        htmlDescriptionDetail:
          $ref: '#/components/schemas/htmlDetail'
        focus:
          $ref: '#/components/schemas/focus'
        xMin:
          $ref: '#/components/schemas/xMin'
        xMax:
          $ref: '#/components/schemas/xMax'
        markers:
          $ref: '#/components/schemas/markers'
        unitDesc:
          $ref: '#/components/schemas/unitDesc'
        legend:
          $ref: '#/components/schemas/legend'
        skipped:
          description: One entry for each GP practice participating in the chosen group but excluded from this chronic care program
          type: array
          items:
            type: object
            properties:
              name:
                description: Name of the GP practice
                type: string
              agb:
                description: AGB of the GP practice, if known.
                type: integer
                format: int32
                minimum: 1
                maximum: 99999999
              skipReason:
                description: Human readable string describing why this GP practice is excluded (in dutch, *HTML*).
                type: string
            required:
              - name
              - skipReason
        participants:
          description: One entry for each GP practice participating in the chosen group and in this chronic care program
          type: array
          items:
            type: object
            properties:
              gpis:
                $ref: '#/components/schemas/GPIS'
              name:
                $ref: '#/components/schemas/name'
              agb:
                $ref: '#/components/schemas/properties-agb'
              amplitude:
                description: |-
                  The relative weight of this practice compared to all practices (the ratio of this practice's population vs. the total population).
                  A higher number means this practice has many patients in its `population`, a lower meaning means fewer.
                type: number
                format: double
                minimum: 0
                maximum: 1
              population:
                description: |-
                  The amount of patients for this GP practice that are relevant for this indicator: Each patient in this population is assigned
                  into one of the categories of this indicator (which may be the 'not measured for this patient' category).
                type: integer
                minimum: 0
                format: int32
              values:
                description: |-
                  For each entry in the `legend`, one value representing how many patients are assigned into that category. For legend-less indicators,
                  this array will only contain a single number.
                type: array
                items:
                  type: integer
                  minimum: 0
                  format: int32
            required:
              - gpis
              - name
              - amplitude
              - population
              - values
        cache:
          type: boolean
          description: If true, the indicator was retrieved from the API cache. The indicator is only retrieved from the cache if there is no recent calculation available in the database and if the indicator won't change anymore. This is the case when it was calculated with a reference date in the past and for which a certain period no new GPIS-data is provided. The cached indicator reflects the indicator definition on the reference date. A cached indicator is not updated when the definition changes.
          example: true
      required:
        - group
        - key
        - title
        - type
        - refDate
        - description
        - markers
        - skipped
        - participants
    properties-key:
      description: Unique identifier, not to be shown to the user, for referring to this indicator set in other API calls
      type: string
      example: ZOO-dm
    properties-name:
      description: Human readable dutch text; should fit in one line.
      type: string
      example: Diabetes Mellitus type 2 – per InEen 2023 accreditatie
    calculating:
      description: |-
        Calculating an indicator set report takes some time; this API responds with a `calculating` value of less than 1.0 and
        no `chapters` section (thus, no data). Call this endpoint a few times to get status updates. Once calculation is complete,
        `1.0` will be returned and `chapters` will be provided.
      format: number
      minimum: 0
      maximum: 1
    employee-string:
      type: string
      description: A string that identifies the employee who is setting this policy.
      example: Mien Dobbelsteen
    dateTimeZ:
      description: Timestamp in complete basic representation of date and time according ISO 8601.
      type: string
      format: datetime
      example: 19700131T235901Z
    CallupPolicyType-enum-short:
      type: string
      enum:
        - PatientIndicator
        - PatientOnly
        - IndicatorUser
      example: PatientIndicator
    CallupPolicyFrequency:
      description: The stated patient should have the stated indicator checked with this frequency instead of the standard frequency as per the care protocol for this care program. The callup state is modified accordingly, except for the special value of `never` which means te callup state is reported as `-` ('not relevant for this patient').
      type: string
      enum:
        - quarter
        - sixMonths
        - year
        - twoYear
        - threeYear
        - fiveYear
        - never
      example: never
    CallupPolicyType-enum-full:
      description: |-
        Call-up policies type. Various types are supported:

        <dl>
        <dt><code>PatientIndicator</code></dt>
        <dd>A policy that applies to a specific patient for a specific indicator. For example, a policy might capture the notion "This patient is an amputee and therefore, the frequency of doing foot inspections for chronic diabetes care should be 'never', forever". Or "This patient is going to receive an eye operation next year, therefore funduscopy is not useful, and the specialist team managing their eye care is responsible for it until after the operation and its recovery. Frequency set to 'never', until 2026-08-01". Such policies always refer to a specific patient and a specific indicator, may or may not have an expiry date, and always have a custom frequency.

        The effect of this policy is to modify the 'callup state' for that patient/indicator combination. For example, the amputee would receive a `-` state for 'foot inspection' (indicating: Foot inspection is not relevant for this patient) instead of a `0` (indicating: Foot inspection must be done this quarter). Naturally, any policy that expires _before_ the `refDate` of a callup list you're asking for doesn't apply.</dd>

        <dt><code>PatientSnoozed</code></dt>
        <dd>A policy that applies to a specific patient for a certain care program type (e.g. `COPD`), and indicates that providing chronic care at the GP level is not possible for a limited time. For longer 'snoozing' the advice is generally to set the GPIS based registration of chronic care participation (i.e. the value 'COKZ' (COPD chronic care participation) to 'No'), but when the situation is temporary and a medical operator knows when the situation ends, this policy can be used instead, which has the advantage of restoring the patient to chronic care reporting automatically when the policy is expires. `expiry` is mandatory for this type of policy.

        The effect of this policy is to default the patient's call up plan (the `chosenStatus` is `byPolicy`) to `doNotCallup` until the policy expires.</dd>

        <dt><code>UserIndicator</code><dt>
        <dd>WARNING: Not current available (not implemented yet).

        This policy applies to a specific indicator, for all patients. Can be used to represent "our ECG machine is broken until 2025-10-01" for example, or "providing flu injections is done by a different team than DM chronic care therefore this indicator does not apply to me".

        The effect of this policy is to mark it as 'not relevant' for all patients. It is not possible to configure an alternate frequency; that would be a modification of the protocol itself which can be implemented by contacting Zorg op Orde to discuss a customised protocol.
      type: string
      enum:
        - PatientIndicator
        - PatientOnly
        - IndicatorUser
      example: PatientIndicator
