Page tree
Skip to end of metadata
Go to start of metadata

The first release of the WMDA Search, Match & Connect API is now available. 

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. If so desired you can filter on: 
    • createdBy     (the user that created the patient)
    • status           (the status of the patient. This is "NEW" initially)
  • Request info on an individual patient

What can I not do using the API? 

The following actions are NOT yet available in our production environment, but available for public testing in our staging environmenthttps://staging-search.wmda.info/api/v1/docs

  • Changing the status of a patient
  • Starting a search
  • Updating a search
  • Retrieving search results 

How can my organisation make use of the patient API?

  1. Find out who is the technical person within or outside your organisation who can help you test the API. 
  2. Send an e-mail to support@wmda.info in which you indicate that you would like to use the WMDA Search, Match & Connect API. 
  3. 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. 
  4. 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?

  1. OAuth 2.0 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 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.
  2. You should receive an e-mail in return as well as login credentials in the way you indicated in your e-mail. 
  3. Access to your internal systems
  4. Basic knowledge or REST APIs
  5. Knowledge and skills in developing a connection between your internal system and WMDA Search & Match API. 
  6. 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://search.wmda.info/api/v1/docs

How do I perform authentication?

Authentication takes place using OAuth 2.0. After you have received credentials from WMDA Support you can get started.
You will receive two items: 

  • client_id
  • client_secret

The OAuth 2.0 grant type is:    "client_credentials". We do not support other grant types. 

Scope:  <no scope>    (please leave empty)

This is what it should look like in Postman. 



You can also execute the following call: 

{
	"grant_type": "client_credentials",
	"client_id": "{{client_id}}",
	"client_secret": "{{client_secret}}"
}

You should receive back the following: 

{
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "{{ACCESS_TOKEN}}"
}

You can use the access_token in the "Authorization" header. Make sure it is prepended by "Bearer ". An example of such an "Authorization" header would be:
"Bearer sdsddashdfjklhjkfjkl;fhasdkhkfhjkfhasdjklfkjhfhjklfhjkldjklfdjkldfhjkldhjklfdghkfjhkdjlhkdjkghfk.gadkhlvgfdhfjkl;adghfhaoghKSHSGHYUSG782782892YUOHJKKGH"


Where can I find the API specifications? 

You can find the specifications here: 

To perform testing you can use following URL

https://staging-search.wmda.info/api/v1/docs

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

For specific information on what can be done in the production environment please check: 

https://search.wmda.info/api/v1/docs

How do I use the Swagger documentation page? 

Before you can perform calls to the API, you should authenticate and authorize. You can do this by clicking the "Authorize" button. 

 

You will then see the following pop-up: 

Enter the client_id and client_secret and press "Authorize". You should then see the following pop-up. 

Press "close" and you should see that the "open lock" has changed to a "closed lock". 

This means that you have been authenticated and authorized. 

Please note: If you receive the following popup you have entered the wrong client_id and client_secret: 

Possibly you have accidentally entered a space character before or after the actual client_secret. 

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 staging environment using the swagger API documentation page. 

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

What should I enter as "userId"?

The contents for the "userId" header should be the e-mail address of the end-user that is currently using your internal system. E.g. if Search coordinator "Jane Smith" is using your organisation's internal system to add a patient to WMDA Search and Match, you should send her e-mail address (e.g. jane.smith@yourorganisation.com) as the "userId" header. This needs to be an e-mail address of a valid user of the Search & Match service. Doing this will also help organise and filter patients because the patient that was created under a certain userId will be visible under the "my patients" of that user on the Search & Match website. Of course, if multiple people within your organisation are using the internal system and triggering the creation of the patient, the correct userId should be sent along. This provides a better audit trail but also makes it easier for each user to find their patients under "My Patients" on the Search & Match website. 

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 "pId"? 

The pId 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. Use the firstname and lastName field if you really need to, but we strongly suggest not providing this info as it is very sensitive information. 
  • You cannot change a pId
  • You are not allowed to use the same pId twice within your organisation

Do you support the refresh_token grant type?

In line with the official standards, we do not support the refresh_token grant type. See https://tools.ietf.org/html/rfc6749#section-4.4.3

"A refresh token SHOULD NOT be included. If the request failed client authentication or is invalid, the authorization server returns an error response as described in Section 5.2."

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. 

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 there are some attributes that are new. What should I enter for these values? 

On the following page you can find out information about each of the fields used in the API: https://share.wmda.info/x/IjmOF
These fields will be added to the data dictionary at a later point in time. 



  • No labels