zoo-api/schemas/PatIdentity.yaml

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: number
  example: 123456789
name:
  description: All relevant info about the patient's name.
  type: object
  properties:
    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
    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
      default: ""
    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
    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 (i.e. not sent).        
      type: string
      example: van der
      default: ""
    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.
          
          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
dob:
  description: |-
    Patient's date of birth.
    
    Note that by convention, patients whose birthdate is unknown (rare, but can happen in certain asylum seeker cases)
    pick a date and tend to pick either `xxxx-01-01` or `xxxx-07-01`. Can, in rare cases, be unavailable - if birth date is not known.    
  type: string
  format: date
  example: 1970-07-01
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 HIS or practice doesn't assign patients to individual GPs,
    or this information isn't known.    
  type: number
  example: 1051234
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:
      description: The post code, in `1234AB` format. If not known, blank.
      type: string
      example: 2611PV
    city:
      description: The city or town.
      type: string
      example: Delft
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"]
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:
      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 left-pad with zeroes.        
      type: number
      example: 101
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.
    
    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.    
  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_).
    
    In rare cases, a patient joined so long ago, this date is no longer known. In this case,
    a sentinel value of `"1900-01-01"` is sent which is presumed to result in the desired behaviour
    (which is to consider this patient as part of this practice's population regardless of how far
    back you want to go).    
  example: 1994-08-20
end_date:
  type: string
  format: date
  description: |-
        If present, patient has exited the practice on this date. (dutch: _uitschrijf datum_).
  default: ""
end_reason:
  description: |-
    Reason patient left the practice (dutch: _reden vertrek_).
    
    This property is never present if `end_date` 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: ""
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"]