|
|
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.
|
|
|
|