Patient and Search API (Integrating Search & Match)

Here is a short introduction to how you can test and use the API within your organisation.

It is very important to realise that the ability to test the API without technical knowledge is limited.

What is the WMDA Search, Match & Connect API?

The WMDA Search, Match & Connect API provides a way in which the internal systems of an organisation (e.g. registry or transplant centre) can communicate with the Search and Match environment.
When your internal system implements this API, the patients from your internal system no longer need to be entered manually into the WMDA Search & Match website, saving time and reducing the risk of errors.
At a later stage, we plan to add the capability to start searches for your patients and retrieve the results, all through your internal system (when implemented by your organisation).
Some features might not become available to some organisations due to license restrictions.

What can I currently do using the API?

The following actions are currently active using the API:

Adding a patient
Updating a patient
Listing all patients.
Request info on an individual patient
Starting a donor search
Updating a donor search
Retrieving donor search results
Changing the status of a patient
Starting a cord search
Updating a cord search
Retrieving cord search results
Retrieve full report for donors
Retrieve full report for CBUs
For more features see https://share.wmda.info/x/bAFuG

What can I not do using the API?

All relevant features are available. Anything that can be done via the front end can also be done through the API as the front end also works via the same API.

How can my organisation make use of the patient and Search API?

Find out who is the technical person within or outside your organisation who can help you test the API.
Send an e-mail to support@wmda.info in which you indicate that you would like to use the WMDA Search, Match & Connect API.
Please include the following information:
→ Preferred method of providing the OAuth 2.0 login credentials. It needs to be a secure method such as a PGP encrypted file (please provide your public key) or a mobile phone number to which we can send you (part of) the password.
You should receive an e-mail in return as well as login credentials in the way you indicated in your e-mail.

What do I, as API implementer, need to use/test the API?

API credentials. Please send an e-mail to support@wmda.info in which you indicate that you would like to use the WMDA Search, Match & Connect API.
Please include the following information:
→ Preferred method of receiving the API login credentials. It needs to be a secure method such as a PGP encrypted file (please provide your public key) or a mobile phone number to which we can send you (part of) the password.
You should receive an e-mail in return as well as login credentials in the way you indicated in your e-mail.
Access to your internal systems
Basic knowledge or REST APIs
Knowledge and skills in developing a connection between your internal system and WMDA Search & Match API.
Optional: Postman or other API development environment

System requirements for implementing the API

The implementation of the API does not set requirements for an end user system, because the API will need to be implemented at the back-end of the registry internal system. There are therefore two options:

Deploy software which has built in support for the WMDA Search, Match & Connect API. Currently there is no off-the-shelf software which does that, but Steiner Ltd. has indicated that they will implement the patient and search API in their next release.
Integrate it into your internal system yourself. This requires:
- Access and ability to make changes and additions to the existing software of your internal registry system.
- Internet access from back-end system.
- Your internal system needs to have been written in a programming language which is able to connect to a RESTful API. This is almost any language.
- Available processing resources on the system where integration takes place

Which formats are supported?

Only "JSON" is accepted for input and responses. More info can be found using https://sandbox-search-api.wmda.info/swagger/index.html

How do I perform authentication?

Please check API authentication for more info on API authentication.

Where can I find the API specifications?

You can find the specifications here:

To perform testing you can use following URL

https://sandbox-search-api.wmda.info/swagger/index.html

This is also where you can perform calls to the API.

Do you have JSON schemas for the request and response bodies?

Yes. You can find them below:

How do I use the Swagger documentation page?

First you will need to request a bearer token. Instructions for this can be found here: API authentication

You then will need to enter the bearer token in the swagger page.

First click on the "Authorize" button.

Then enter the bearer token in the "Value" field.
click "Authorize"

Please do not refresh the page, because this will re-load it and you will need to re-authenticate.

You should now be able to execute API calls to the sandbox environment using the swagger API documentation page.

You can also download the following JSON file and import it into e.g. Postman: https://sandbox-search-api.wmda.info/swagger/v1/swagger.json

When updating a patient, can I send a partial patient to the API to just update that part?

No, you should always send the entire patient record, including things that are not changing. Otherwise, all fields that are not sent will be nullified or you'll receive an error because a required field is missing.

What is the "patientId"?

The patientId is the "patient id" that you can find in the web GUI.

Please keep in mind:

It is not allowed to use real patient names.
You cannot change a patientId
You are not allowed to use the same patientId twice within your organisation
If you keep the legalTerms value at "false" or don't send it when creating a new patient, you have indicated you will not comply with legal terms and therefore are not allowed to store a pId.

How long does it take for the results of a patient upload via the API to appear on the Search & Match website?

It will be visible directly. There is no delay.

How do the patient statuses affect behaviour?

The following flow diagram describes how and when patient status can be updated and what the consequences are.

I have a question that is not listed here

Please contact WMDA Support at the following e-mail address: support@wmda.info

I see that for search results endpoints, there is no indication whether it is serology or DNA typing. Why is that?

When requesting search results via the /searches/searchResults/donors or /searches/searchResults/cbus endpoint, you may notice that the HLA does not explicitly tell whether it is DNA or serology typing. It may therefore look like this:

"hla": {
		"a": {
			"field1": "01:01",
			"field2": "03:01"
		},
		"b": {
			"field1": "38",
			"field2": "62"
		},
		"c": {
			"field1": "3",
			"field2": "3"
		},
		"dpa1": {
			"field1": null,
			"field2": null
		},
		"dpb1": {
			"field1": null,
			"field2": null
		},
		"dqa1": {
			"field1": null,
			"field2": null
		},
		"dqb1": {
			"field1": null,
			"field2": null
		},
		"drb1": {
			"field1": "04:BMS",
			"field2": "11:APB"
		},
		"drb3": {
			"field1": null,
			"field2": null
		},
		"drb4": {
			"field1": null,
			"field2": null
		},
		"drb5": {
			"field1": null,
			"field2": null
		}
	}

As you can see the HLA is a mix of typing at DNA level (with and without MAC codes) and serology typing. These are the values that are always displayed in the front end of Search & Match when viewing search results.

The actual information from the donor may be DNA typing and/ or serology. The following logic is used to determine which value is returned in the search results API:
If there is DNA level typing at the locus → return DNA level typing. This regardless of whether there is serology typing. DNA typing always overrules serology typing.

If there is ONLY serology typing at the locus → return serology typing.

How can I see all typing for a donor from my search result?

If you want to see all available typing for a donor, you should call the "full report" endpoints (/searches/donors/{searchResultsId} or /searches/cbus/{searchResultsId}), There you will get all information we can provide for the donor. Please keep in mind that for ATLAS searches, this does not include any locus other than A, B, C, DRB1, DQB1 and DPB1.

Page tree