diff --git a/zoo-api.yaml b/zoo-api.yaml index b8a5935..a7018c8 100644 --- a/zoo-api.yaml +++ b/zoo-api.yaml @@ -50,6 +50,7 @@ paths: tags: - core summary: Available springboard apps + description: WorkInProgress responses: '200': description: List of available apps @@ -95,104 +96,117 @@ paths: If unknown or left blank, will be 9 zeroes. type: string example: 123456789 - naam: + name: description: All relevant info about the patient's name. type: object properties: - voornaam: + 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 - voorvoegsel_achternaam: + 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 HIS. + type: string + example: MA + infix_own: 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 - achternaam: + own_lastname: 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 - voorvoegsel_geslachtsnaam_partner: + infix_partner: 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. type: string example: van der - geslachtsnaam_partner: + partner_lastname: 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. type: string example: Dussen - geslacht: - description: Patient's gender. + 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: man + example: V enum: - - man - - vrouw - - anders - geboortedatum: + - M + - V + - O + dob: description: |- - Patient's birth date. + Patient's date of birth. Note that by convention, patients whose birthdate is unknown pick a date and tend to pick either `xxxx-01-01` or `xxxx-07-01`. Can, in rare cases, be blank - if birth date is not known. type: string format: date example: 1970-07-01 - adres: + address: description: Patient's address (where they live). type: object properties: - straat: - description: Full name of the street; can be blank if not known or not provided, and excludes hous number. + street: + description: Full name of the street; can be blank if not known or not provided, and excludes house number. type: string example: Lange Geer - huisnummer: + hn: description: |- - A combination of house number (digits) and 'house number addition'. If an addition is present, the - entry is formatted as `12 ABC` where the digits representing house number are always at the front, then - a space, then the remainder is the 'house number addition'; if no addition, no space is included. - - A number is always present; possibly 0 to indicate no known house number or the extremely rare case of - a house without a house number. + 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. + type: integer + example: 4 + hn_suffix: + description: |- + Often empty, the string that follows the numeric part of the address house number. For example, `"A"`, or + `"k22"`. type: string - example: 4 A + example: A postcode: description: The post code, in `1234AB` format. If not known, blank. type: string example: 2611PV - plaats: + city: description: The city or town. type: string example: Delft contact: type: object properties: - mobiel_telefoonnummer: - description: |- - Patient's mobile number; if not known, a blank string, otherwise, in `+316...` format: A plus, followed by the country code, followed by the phone number. - type: string - example: +316123456789 - vast_telefoonnummer: + tel: description: |- - Patient's landline number; if not known, a blank string, otherwise, in `'+3115...` format: A plus, followed by the country code, followed by the phone number. - type: string - example: +31701234567 + 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. If not known, a blank string. - type: string - example: info@zorgoporde.nl - verzekering: + 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"] + insurance: type: object properties: - verzekeringsnummer: + policy_number: description: |- - Patient's insurance registration number. If not known or not insured, a blank string. + Patient's insurance registration number (dutch: _polisnummer_). If not known or not insured, a blank string. type: string example: 123456789012345 uzovi: @@ -201,6 +215,65 @@ paths: 4 digits exactly, 0-left-padded if needed. If unknown or not insured, 4 zeroes. type: string example: 3331 + patid: + description: |- + Patient's "public" ID, as used and shown on the HIS patient page. Not necessarily unique, + and not necessarily present; 0 indicates no patid is known or this HIS does not use (numeric) + public IDs. + type: number + example: 1234 + pat_unid: + description: |- + Patient's unique and persistent ID in HIS. Usually identical to `patid` but certain HISes may + use UUID, or has globally unique keys (e.g. very large numbers). Can be blank, but only + if supplying HIS does not send them. + type: string + example: 1234 + start_date: + type: string + format: date + description: |- + Date patient joined the practice (dutch: _inschrijf datum_). If blank, patient joined a + long time ago. By convention if programming a system that requires a value, a sentinel + value of `"1900-01-01"` is suggested for this case. (when reading from this API, map + the empty string onto that date if you prefer not having blank/NULL values). + example: 1994-08-20 + end_date: + type: string + format: date + description: |- + If not blank, patient has exited the practice on this date. (dutch: _uitschrijf datum_). + example: "" + end_reason: + description: |- + Reason patient left the practice (dutch: _reden vertrek_). + This will always be blank if `end_date` is blank. 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 + example: "" + doctor: + description: |- + If known, the AGB code of the primary care GP (dutch: _Inschrijf arts_). Value 0 indicates + this HIS or practice doesn't assign patients to individual GPs, or this information isn't + known. + type: number + example: 1051234 + 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): + - `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 '400': description: The request is invalid; for example, it doesn't contain the required `BSN` parameter. '401':