View Source

4.1 - Start search

A POST to the searches endpoint is used to submit a search request to the Search & Match Service. This call returns a searchId of the search.

Post

searches

Field	Details
wmdaId*	integer example: 123456 nullable: false
matchEngine*	integer nullable: false Unique identifier of match engine used in the search. Allowed: 2 (HAP-E), 3 (ATLAS). Enum: Array [ 2 ]
searchType*	string example: DREnum: Array [ 2 ]
overallMismatches	integer default: 0Enum: Array [ 8 ]
lociToBeConsidered	[...]
isCbuAbLowDrb1HighResolution	boolean default: false nullable: true

Field	Details
searchId	integer nullable: false minimum: 1

4.2 - Search summary

A GET to the searches/{searchId} endpoint is used to request a search summary of a search. It also contains the status of the search and can therefore be used to check whether the search is done.

Get

searches/{searchId}

Field

Details

searchId*

integer

Unique identifier of the search. Can be determined by retrieving the patient search summary

Field	Details
patient	{...}
searchId*	integer nullable: false minimum: 1
searchType*	stringEnum: Array [ 1 ]
matchEngine*	integer nullable: false Unique identifier of match engine used in the search. Allowed: 2 (HAP-E), 3 (ATLAS). Enum: Array [ 2 ]
overallMismatches*	integer default: 0Enum: Array [ 8 ]
status*	string nullable: falseEnum: Array [ 3 ]
summary*	{...}
inexplicable*	integer nullable: true Total number of donors whose phenotype cannot be explained by known haplotype
statistics*	{...}
error*	{...} nullable: true
lociToBeConsidered	[...]
lastUpdated	string($date-time) nullable: false maxLength: 255 needed to help determine when the patient can be automatically moved to STP state

4.3 - Retrieve all searches for a patient

A GET to the searches/patientSearches/{wmdaId} endpoint is used to retrieve an overview off all searches that have been performed for a specific patient.

Get

searches/patientSearches/{wmdaId}

Field

Details

wmdaId*

integer

wmdaId of patient you want to find search information for. This is NOT the patientId, but the wmdaId you received in the response body after creating your patient.

Field	Details
searchId*	integer nullable: false minimum: 1
matchEngine*	integer nullable: false Unique identifier of match engine used in the search. Allowed: 2 (HAP-E), 3 (ATLAS). Enum: Array [ 2 ]
searchType*	stringEnum: Array [ 1 ]
overallMismatches*	integer default: 0Enum: Array [ 8 ]
status*	string nullable: falseEnum: Array [ 3 ]
summary*	{...}
lociToBeConsidered*	[...]
lastUpdated*	string($date-time) nullable: false maxLength: 255 needed to help determine when the patient can be automatically moved to STP state
inexplicable	integer nullable: true Total number of donors whose phenotype cannot be explained by known haplotype
statistics	{...}
error	{...} nullable: true

4.4 - Search results - Donors

A POST to the searches/searchResults/donors endpoint is used to retrieve search results with adult donors. Pagination is possible and optional filters can be provided. If only interested in recent changes to the search results, this can be achieved using a filter on "recordLastUpdatedFrom" field.

Post

searches/searchResults/donors

Field	Details
pagination	{...}
searchId*	integer nullable: false minimum: 1
filters	{...}
sortBy	string nullable: true default: standard Enum: Array [ 2 ]

Field	Details
paging*	{...}
searchResults*	[...]

4.5 - Search results - CBUs

A POST to the searches/searchResults/cbus retrieveSearchResultsDonors endpoint is used to retrieve search results with cord blood units. Pagination is possible and optional filters can be provided. If only interested in recent changes to the search results, this can be achieved using a filter on "recordLastUpdatedFrom" field.

Post

searches/searchResults/cbus

Field	Details
pagination	{...}
searchId*	integer nullable: false minimum: 1
filters	{...}
sortBy	string nullable: true default: standardEnum: Array [ 2 ]
threeFourMismatchSortBy	string nullable: true default: resolutionScoreEnum: Array [ 3 ]
secondarySortBy	string nullable: true default: tncCountEnum: Array [ 2 ]

Field	Details
paging*	{...}
searchResults*	[...]

4.6 - Mark selected donor

A POST to the searches/selected/donors endpoint is used to select a donor. This endpoint can be used to highlight a donor of interest.

Post

searches/selected/donors

Field

Details

wmdaId

integer

wmdaId of patient you want to find search information for. This is NOT the patientId, but the wmdaId you received in the response body after creating your patient.

grid

string
nullable: true
maxLength: 19
minLength: 19
example: 9991012070433202000

setAsSelected

boolean
nullable: false

set (true) or unset (false) the indicated grid or cordId as a selected stem cell source for this patient

N/A

4.7 - Mark selected CBU

A POST to the searches/selected/cbus endpoint is used to select a donor. This endpoint can be used to highlight a CBU of interest.

Post

searches/selected/cbus

Field	Details
wmdaId	integer wmdaId of patient you want to find search information for. This is NOT the patientId, but the wmdaId you received in the response body after creating your patient.
cordId	string nullable: true maxLength: 25 example: 9991012070433202000 cordId of the CBU.
donorRegistryIon	integer nullable: false minimum: 1000 maximum: 9999 example: 1234
setAsSelected	boolean nullable: false set (true) or unset (false) the indicated grid or cordId as a selected stem cell source for this patient

N/A

4.8 - Get list of registries that appear in search results

A GET to the searches/{searchId}/searchResults/registries endpoint is used to retrieve an overview off all the registries that appear in the search results of a specific donor search.

Get

searches/{searchId}/searchResults/registries

Field

Details

searchId*

integer

Unique identifier of the search. Can be determined by retrieving the patient search summary

Field

Details

registries*

{...}

Array of unique registry IONs with their abbreviation and name

4.9 - Get list of cord blood banks that appear in search results

A GET to the searches/{searchId}/searchResults/cbbs endpoint is used to retrieve an overview off all the registries that appear in the search results of a specific donor search.

Get

searches/{searchId}/searchResults/cbbs

Field

Details

searchId*

integer

Unique identifier of the search. Can be determined by retrieving the patient search summary

Field

Details

cbbs*

{...}

Array of unique cbbs bank manufacterer IDs with their abbreviation and name

4.10 - Full report - Donors

A GET to the searches/donors/{searchResultsId} endpoint retrieves all available information of a specific donor in a search result.

Get

searches/donors/{searchResultsId}

Field

Details

searchResultsId*

integer

Unique identifier of the donor within a search result. This is the "id" field within searchResult

Field	Details
searchId	integer nullable: false minimum: 1
searchType	string Enum: Array [ 1 ]
matchDuration	integer minimum: 0 nullable: true example: 30 time in seconds that the search took to run on the matching engine
patient	{...}
search	{...}
donor	{...}

4.11 - Full report - CBUs

A GET to the searches/cbus/{searchResultsId} endpoint retrieves all available information of a specific CBU in a search result.

Get

searches/cbus/{searchResultsId}

Field

Details

searchResultsId*

integer

Unique identifier of the search. Can be determined by retrieving the patient search summary

Field	Details
searchId	integer nullable: false minimum: 1
searchType	stringEnum: Array [ 1 ]
matchDuration	integer minimum: 0 nullable: true example: 30 time in seconds that the search took to run on the matching engine
search	{...}
patient	{...}
cbu	{...}

4.12 - Refresh all searches for a patient

A POST to the searches/refreshAllPatientSearches endpoint is used to restart all searches for this patient and retrieve the new results.

Post

searches/refreshAllPatientSearches

Field	Details
wmdaId*	integer example: 123456 nullable: false

N/A

4.13 - Restart a single search

A POST to the searches/searchResultsRefresh endpoint is used to restart all searches for this patient and retrieve the new results.

Post

searches/searchResultsRefresh

Field	Details
searchId*	integer example: 123456 nullable: false

Field	Details
newSearchId	integer example: 123457 nullable: false

4.14 - Suggested use of API endpoints

Below is a diagram indicating the suggested use of some of the API endpoints. More API endpoints are available and the API implementer may choose to implement the endpoints in another order.

@startuml
<style>
diamond {
    BackgroundColor #ccf
  }
</style>

#palegreen:repeat:request token from 'https://login.microsoftonline.com/{tenantId}/oauth2/token';
repeat while (Valid bearer token from the Patient and Search API?) is (no)
->yes;
#palegreen:create patient: POST /patients;
#lightblue:HTTP201 created: Response body contains 'wmdaId' for this patient;
#palegreen:Start search for patient using wmdaId POST to /searches;
#lightblue:repeat:HTTP201 created: Response body contains 'searchId' for this patient;
#palegreen:repeat:Check search status: GET to /searches/{searchId};
backward: running;
repeat while (What is the 'status' in the response body?)
:completed;
split
#gold:Donor;
#AntiqueWhite:Retrieve search results: POST to /searches/searchResults/donors;
#pink:Pick one or more donors;
#AntiqueWhite:Use 'id' field for that donor to perform GET to
 /searches/donors/{searchResultsId} to get full report for this donor;
split again
#gold:CBU;
#AntiqueWhite:Retrieve search results: POST to /searches/searchResults/cbus;
#pink:Pick one or more CBUs;
#AntiqueWhite:Use 'id' field for that donor to perform GET to 
/searches/cbus/{searchResultsId} to get full report for this CBU;
split again
#gold:ADCU;
#AntiqueWhite:Retrieve search results: POST to /searches/searchResults/adcus;
#pink:Pick one or more ADCUs;
#AntiqueWhite:Use 'id' field for that donor to perform GET to
 /searches/adcus/{searchResultsId} to get full report for this ADCU;
endsplit
split
#palegreen:Refresh all searches for a patient: POST to /searches/refreshAllPatientSearches;
split again
#palegreen:Refresh single search: POST to /searches/searchResultsRefresh;

@enduml