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: ../schemas/date.yaml - 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: '../zoo-api.yaml#/components/parameters/Authorization' responses: '200': description: |- list of patients content: application/json: schema: type: object properties: gpis: $ref: '../schemas/IndicatorSet.yaml#/properties/gpis' key: $ref: '../schemas/IndicatorSet.yaml#/properties/key' name: $ref: '../schemas/IndicatorSet.yaml#/properties/name' careprogram: $ref: '../schemas/IndicatorSet.yaml#/properties/careprogram' refDate: $ref: '../schemas/IndicatorSet.yaml#/properties/refDate' calculating: $ref: '../schemas/IndicatorSet.yaml#/properties/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. required: - title patients: type: array items: type: object properties: patPubId: $ref: '../schemas/PatIdentity.yaml#/patPubId' patUnid: $ref: '../schemas/PatIdentity.yaml#/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: ../schemas/date.yaml 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: ../schemas/date.yaml 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: ../schemas/employee-string.yaml timestamp: type: string description: The policy was created (set) at this time. $ref: ../schemas/dateTimeZ.yaml required: - type required: - patUnid - doctor - byPolicyStatus - chosenStatus - status - dob - state required: - gpis - key - name - refDate - calculating '401': $ref: '../zoo-api.yaml/#/components/responses/NoAuth' '403': $ref: '../zoo-api.yaml#/components/responses/NoAccess' '404': description: The provided `setKey` doesn't refer to a valid program.