3.1 - Patient Identification 

A patientId may be provided when registering a new patient in WMDA Search & Match. Upon registration, a wmdaId will be assigned and returned. The wmdaId itself is guaranteed to be globally unique, though it cannot guarantee that the same patient is not registered by multiple organisations using the same patientId or with different patientId's within the same organisation. The wmdaId must be used to identify the patient in all calls to the Search, Match & Connect (SMC) service after the initial patient registration.

 

Patient Identifiers

IdentifierDescription
patientId
  • Provided by the local registry system.  
  • Should be worldwide unique.
    • Should follow the construct of ION + local patient id. 
      • The ION to be used is the ION of the patient registering registry (PR).
  • Should be provided as a user-friendly (displayable) id for use on screens and on documentation.
wmdaId
  • Generated by the central (SMC) system.
  • Must be globally unique.
  • Must be used for all system-to-system patient identification after the initial patient registration.

3.2 - Create Patient

A POST to the patients endpoint is used to submit a patient to the Search & Match Service. This call returns a wmdaId for the patient.

Post
patients
FieldDetails
patientIdstring
maxLength: 17
nullable: true
example: 98761234P

Organisation unique identifier for patient. Cannot be set unless "legalTerms" is set to "true". Do not use real names here.

hla*{...}
idm{...}
dateOfBirthstring($date)
nullable: true
maxLength: 10
example: 1961-05-27
diagnosis{...}
diseasePhase

string
nullable: true

Enum:
Array [ 48 ]

ethnicity

string
nullable: true

Enum:
Array [ 21 ]

poolCountryCodestring
maxLength: 2
pattern: ^[A-Z]{2}
nullable: true
example: NL

ISO 3166-1 alpha-2 Country Code (capitalized)

transplantCentreIdstring
maxLength: 10
nullable: true
example: TC X
abo

string
nullable: true

Enum:
Array [ 4 ]

rhesus

string
nullable: true

Enum:
Array [ 2 ]

weightinteger
nullable: true
minimum: 1
maximum: 999
example: 76
sex

string
nullable: true

Enum:
Array [ 2 ]

legalTermsboolean
nullable: true
default: false
example: true

If not set to true, then patientId will not be stored.

FieldDetails
wmdaIdinteger
example: 123456
nullable: false

3.3 - Update Patient

A PUT to the patients endpoint is used to update a patient with the Search & Match Service.  An update to search relevant information, such as HLA, ethnicity or pool will result in a refresh of the search.

Put
patients
FieldDetails
patientIdstring
maxLength: 17
nullable: true
example: XY1234P

Organisation unique identifier for patient. Cannot be set unless "legalTerms" is set to "true". Do not use real names here.

A patient ID can only be updated when it was not set before. 

hla*{...}
idm{...}
dateOfBirthstring($date)
nullable: true
maxLength: 10
example: 1961-05-27
diagnosis{...}
diseasePhase

string
nullable: true

Enum:
Array [ 48 ]

ethnicity

string
nullable: true

Enum:
Array [ 21 ]

poolCountryCodestring
maxLength: 2
pattern: ^[A-Z]{2}
nullable: true
example: NL

ISO 3166-1 alpha-2 Country Code (capitalized)

transplantCentreIdstring
maxLength: 10
nullable: true
example: TC X
abo

string
nullable: true

Enum:
Array [ 4 ]

rhesus

string
nullable: true

Enum:
Array [ 2 ]

weightinteger
nullable: true
minimum: 1
maximum: 999
example: 76
sex

string
nullable: true

Enum:
Array [ 2 ]

legalTermsboolean
nullable: true
default: false
example: true

If not set to true, then patientId will not be stored.

wmdaId*integer
example: 123456
nullable: false
None specified

3.4 - Update Patient Status

A PUT to the patients/status endpoint is used to update a patient's search status with the Search & Match Service.  Allowable status values are SUS, PRE, ACT and STP.  A new patient is defaulted to the new (NEW) state.  Under the NEW state, searches must be requested explicitly.  When doing so, the patient is moved to the PRE state. Under the ACT state, searches will be kept up to date automatically.  SUS will stop automatic updates to searches, but results will remain for 42 days.  STP will terminate the search and delete all search results.

The diagram below displays the full logic of which patient state changes are allowed and the effect on automatic updating of search results. 

Patient registryAPI/GUICreate patientPatient status cannot be changedPatient status = "NEW"Change statusNot allowedPatient status = "STP"Start searchPatient status changed happened automatically due to start searchPatient status = "PRE"No automatic updates of search resultsChange statusNot allowedSTP, SUS or ACTcurrent statePREPatient status = "SUS"No automatic updates of search results \nPrevious search results remain availablePatient status = "ACT"Automatic updates of search resultsPatient status = "STP" All search results removedchange status again?yesPRE, SUS or ACTSTPNEW, PRESTPSUSACTno


Put
patients/status
FieldDetails
wmdaId*integer
example: 123456
nullable: false
newStatus*

string
nullable: false

Enum:
Array [ 4 ]

changeReasonstring
nullable: true

Reason why the change was made. Mandatory when changing to "STP"

Enum:
Array [ 21 ]
FieldDetails
wmdaId*integer
example: 123456
nullable: false
status*

string
maxLength: 3
nullable: false

Enum:
Array [ 4 ]

changeReasonstring
maxLength: 3
nullable: true

Reason why the change was made. Mandatory when changing to "STP"

Enum:
Array [ 21 ]

3.5 - Retrieve Patient

A GET to the patients endpoint is used to retrieve an individual patient's information from the Search & Match Service.

Get
patients 
FieldDetails
wmdaId*integer
example: 123456
nullable: false
FieldDetails
patientId*string
maxLength: 17
nullable: true
example: XY1234P

Organisation unique identifier for patient. Cannot be set unless "legalTerms" is set to "true". Do not use real names here.

status*

string
nullable: false

Enum:
Array [ 5 ]

hla*{...}
idm*{...}
dateOfBirth*string($date)
nullable: true
maxLength: 10
example: 1961-05-27
diagnosis*{...}
diseasePhase*

string
nullable: true

Enum:
Array [ 48 ]

ethnicity*

string
nullable: true

Enum:
Array [ 21 ]

poolCountryCode*string
maxLength: 2
pattern: ^[A-Z]{2}
nullable: true
example: NL

ISO 3166-1 alpha-2 Country Code (capitalized)

transplantCentreId*string
maxLength: 10
nullable: true
example: TC X
abo*

string
nullable: true

Enum:
Array [ 4 ]

rhesus*

string
nullable: true

Enum:
Array [ 2 ]

weight*integer
nullable: true
minimum: 1
maximum: 999
example: 76
sex*

string
nullable: true

Enum:
Array [ 2 ]

legalTerms*boolean
nullable: true
default: false
example: true

If not set to true, then patientId will not be stored.

wmdaId*integer
example: 123456
nullable: false
lastUpdated*string($date-time)
nullable: false
maxLength: 255

needed to help determine when patient can be automatically moved to STP state

lastViewed*string($date-time)
nullable: false
maxLength: 255

needed for sorting patients in the patient list

assignedUserName*string
minLength: 4
maxLength: 100
nullable: true
example: janethesearchcoordinator@lunarregistry.com

typically the e-mail address of the user

3.6 - Retrieve Patient(s)

A GET to the patients/list endpoint is used to retrieve multiple patient's information from the Search & Match Service.  You may define a page size, a specific page number, a series of allowable statuses and may limit to only patients assigned to you.

Post
patients/list

Field

Details

patientId

string
maxLength: 17
nullable: true
example: NL12345P

Organisation unique identifier for patient. Cannot be set unless "legalTerms" is set to "true". Do not use real names here.

limit

integer
nullable: true
default: 100
example: 250

offset

integer
nullable: true
default: 0

onlyMyPatients

boolean
default: 0
nullable: true
example: true

Only return patients assigned to current user.
Field

Details

paging
FieldDetails
limit*integer
default: 100
offset*integer
default: 0
totalCount*integer
minimum: 0
patients
FieldDetails
wmdaId*integer
example: 123456
nullable: false
patientId*string
maxLength: 17
nullable: true
example: XY1234P

Organisation unique identifier for patient. Cannot be set unless "legalTerms" is set to "true". Do not use real names here.

status*

string
nullable: false

Enum:
Array [ 5 ]

dateOfBirth*string($date)
nullable: true
maxLength: 10
example: 1961-05-27
ethnicity*

string
nullable: true

Enum:
Array [ 21 ]

lastUpdated*string($date-time)
nullable: false
maxLength: 255

needed to help determine when patient can be automatically moved to STP state

lastViewed*string($date-time)
nullable: false
maxLength: 255

needed for sorting patients in the patient list

assignedUserName*string
minLength: 4
maxLength: 100
nullable: true
example: janethesearchcoordinator@lunarregistry.com

typically the e-mail address of the user

requests*[...]

3.7 - Assign User To Patient

A PUT to the patients/user endpoint is used to assign a particular user name to a patient within the Search & Match Service.

Put
patients/user
FieldDetails
wmdaId*integer
example: 123456
nullable: false
userName*string
minLength: 4
maxLength: 100
nullable: true
example: janethesearchcoordinator@lunarregistry.com

typically the e-mail address of the user

FieldDetails
succeededboolean
default: true
messagestring
example: Successfully assigned janethesearchcoordinator@lunarregistry.com

3.8 - Register Patient   

There is no registerPatientRequest endpoint.  A patient is registered with a partner registry at the time of request in the form of an embedded Patient block - described in the Admin chapter. 

3.9 - Update Registered Patient (PAT_UPD)

The updateRegisteredPatient message is used to update a registered patient with a partner registry.


Send (Post)Retrieve (Post)
updateRegisteredPatientupdateRegisteredPatientRetrieve
FieldDetails
receivingRegistry*integer
maximum: 9999
minimum: 0
maxLength: 4
minLength: 4
example: 1234

4 digit ION of receiving registry

patient*Embedded Patient Block
FieldDetails
wmdaResponse*Embedded WMDA Response Block
limitinteger
default: 100
shouldPeekboolean
default: false

Set to true if you want messages to remain available after retrieval

messageSequenceNumber

integer
example: 12345

Optional field to request a message with a specific messageSequenceNumber. If that message (no longer) exists then no message will be returned.

FieldDetails
generalInformationEmbedded General Information Block
originalMessage*Embedded Patient Block
metaInformation*Embedded Meta Block

3.10 - Patient Flows


Patient FlowsPatient RegistryPatient RegistryMatch-ConnectMatch-ConnectSearch & MatchServiceSearch & MatchServiceDonor RegistryDonor RegistryRegister PatientCreate PatientReturn WMDA Patient IDModify Patient Update PatientAssign User To PatientRetrieve Patient(s)Retrieve PatientsReturn One or More PatientsMaking RequestsRequest a Donor (patient embedded)Update Registered Patient

3.11 - Patient Life Cycle

In order to prevent unnecessary storage of search results and other patient related information, there are automated processes in place to automatically clean up patients that are not in use. 

After a patient has not been viewed in any way (patient or search results), the patient will be moved to the "Inactive" state in Search & Match. You can see how much time is left until a patient is moved to the "Inactive" (STP) state by going to the patient list. 

Simply clicking on the patient or its search result will reset the timer and will provide you with another 42 days until the patient is automatically moved to the "Inactive" state. 

A patient that has been in the "Inactive" (STP) state for more than 6 months is anonymised and cannot be recovered any more. 

Below are two diagrams that further explain the life cycle of patients in Search & Match with different levels of details

Simplified logic of patient life cycle

Search & Match web siteCreate patientPatient or its search results not viewed for 42 daysPatient automatically set to STP stateAll search results removedno change for > 6 monthsPatient anonymisedPatient no longer accessible or recoverable

Detailed diagram of patient life cycle logic

Patient registry or transplant centreAPI/web front endCreate patientCountdown set to 42 daysNoPatient update orRetrieve patient orRetrieve search results for patientYesCountdown (re)set to 42 daysNo activity on patientCountdown hits 0Patient automatically set to STP stateAll search results removedCountdown set to 6 monthsNoPatient set back to ACT or SUS state via API call or web front endYesCountdown (re)set to 42 daysCountdown hits 0Patient anonymisedPatient no longer accessible or recoverable