⚠Due to planned maintenance you will experience short (<30 min) downtime between 08:00 - 08:30 CET.
Table of Contents |
---|
4.1 - Start
...
search
A POST to the searches The startSearch endpoint is used to submit a search request to the Search & Match Service. This call returns a searchId for of the search.
Post | |||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Send | |||||||||||||||||||||||||||||
startSearch | |||||||||||||||||||||||||||||
Request
|
4.2 - Search summary
The retrieveSearchResultssummary A GET to the searches/{searchId} endpoint is used to request a search summary for of a search. It also contains the status of a the search and can therefore be used to check whether a the search is done.
Request
Response
whichSend | |||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
retrieveSearchResultssummary | |||||||||||||||||||||||||
Get | |||||||||||||||||||||||||
searches/{searchId} | |||||||||||||||||||||||||
| |||||||||||||||||||||||||
| |||||||||||||||||||||||||
| |||||||||||||||||||||||||
|
4.3 -
...
Retrieve all searches for a patient
A GET to the searches/patientSearches/{wmdaId} The retrieveSearchResultsDonors endpoint is used to retrieve search results for donors. Pagination is possible and optional filters can be provided. an overview off all searches that have been performed for a specific patient.
Request
{...}stringtruedefault: standardlimit
Response
[
minItems: 0
minimum: 0example5176
Get | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
searches/patientSearches/{wmdaId} | ||||||||||||||||
| ||||||||||||||||
Send | ||||||||||||||||
retrieveSearchResultsDonors | ||||||||||||||||
pagination | ||||||||||||||||
| ||||||||||||||||
filters | {...} | |||||||||||||||
sortBy | ||||||||||||||||
| ||||||||||||||||
| ||||||||||||||||
paging* | ||||||||||||||||
| ||||||||||||||||
| ||||||||||||||||
id* | ||||||||||||||||
| ||||||||||||||||
offset* | integer default: 0 minimum: 0 example: 0 | |||||||||||||||
totalCount* | integer minimum: 0 example: 2 | |||||||||||||||
searchResults* | ||||||||||||||||
| ||||||||||||||||
| ||||||||||||||||
donorRegistryIon* | ||||||||||||||||
| ||||||||||||||||
| ||||||||||||||||
|
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.
ethnicity*
UK, AF, AS, CA, HI, AFNA, AFSS, ASSW, ASSO, ASCE, ASSE, ASNE, ASOC, CAEU, CAER, CANA, CAAU, HICA, HISA, MX, OT ]idm*antiCmvStatusstringPost | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
searches/searchResults/donors | ||||||||||||||
minimum: 1000 maximum: 9999 example: 1234 | ||||||||||||||
abbreviation* | string example: NL-WMDA maxLength: 24 | |||||||||||||
haplotypeFrequencySetId* | integer nullable: true minimum: 0 example: 15 | |||||||||||||
status* | string nullable: falseEnum: [ AV, TU, RS ] | |||||||||||||
sex* | string nullable: trueEnum: [ M, F ] |
|
nullable: trueEnum:
Array [ 7 ]antiCmvDatestring($date)
nullable: true
maxLength: 10
date of CMV NAT test
cmvNatStatus
|
Expand | ||||||
---|---|---|---|---|---|---|
| ||||||
|
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.
cmvNatDate($date)maxLength10
date of CMV NAT test
abo*[ A, B, O, AB ]}]
Post | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
searches/searchResults/cbus | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
rhesus* | string nullable: trueEnum: [ P, N ] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
registryAccreditationStatus* | string nullable: trueEnum: [ accredited, qualified ] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
firstAccreditationYear* | number minimum: 1990 maximum: 2100 nullable: true example: 2019 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
matchClass* | string example: 9/10 nullable: false | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
nmdpGrade* | string maxLength: 5 example: MPPMP nullable: true A - high-res match on ARD, P - probable match, M - sure Mismatch | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
zeroMismatchProbability* | integer minimum: 0 maximum: 100 nullable: true | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
oneMismatchProbability* | integer nullable: true minimum: 0 maximum: 100 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
twoMismatchProbability* | integer nullable: true minimum: 0 maximum: 100 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
aLocusMatchProbability* | integer nullable: true minimum: 0 maximum: 100 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bLocusMatchProbability* | integer nullable: true minimum: 0 maximum: 100 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cLocusMatchProbability* | integer nullable: true minimum: 0 maximum: 100 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
drLocusMatchProbability* | integer nullable: true minimum: 0 maximum: 100 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
dqLocusMatchProbability* | integer nullable: true minimum: 0 maximum: 100 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
inexplicable* | boolean | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
matchingInformationDpb1* |
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
mismatches* |
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
searchResultRecordState* | string nullable: false default: ExistingEnum: [ Existing, New, Updated, Deleted ] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
searchResultRecordStateUpdatedAt* | string($date-time) nullable: true maxLength: 255 date and time when the last change was registered in the system | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
isSelected* | boolean nullable: true true when this record has been marked as a selected | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
resolutionScore* | number minimum: 0 maximum: 100 nullable: true example: 54 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
resolutionString* | string minLength: 5 maxLength: 5 example: AP-A- nullable: true A - high-res P - low or intermediate, - no typing | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
grid* | string nullable: true maxLength: 19 minLength: 19 example: 9991012070433202000 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
donorId* | string nullable: true example: ABC1234 maxLength: 25 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
donorType* | string nullable: falseEnum: [ D, B ] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
lastContactDate* | string($date) nullable: true minLength: 10 maxLength: 10 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
marrowDonationsCount* | integer nullable: true example: 0 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
pbscDonationsCount* | integer nullable: true example: 1 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
dateOfBirth* | string($date) nullable: true maxLength: 10 example: 1961-05-27 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
hla* |
|
4.4 - Full report - Donors
The retrieveFullReportDonors endpoint is used to retrieve all available information for a specific donor in a search result.
...
Request
...
Response
searchId | integer nullable: false minimum: 1 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
searchType | stringEnum: [ DR ] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
matchDuration | integer minimum: 0 nullable: true example: 30 time in seconds that the search took to run on the matching engine | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
patient |
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
donor |
|
4.5 - Search results - CBUs
The retrieveSearchResultsDonors endpoint is used to retrieve search results for cord blood units. Pagination is possible and optional filters can be provided.
...
Request
pagination | {
} | ||||||||||||||||||||||||||||||||||
searchId* | integer nullable: false minimum: 1 | ||||||||||||||||||||||||||||||||||
filters | {
} | ||||||||||||||||||||||||||||||||||
sortBy | string nullable: true default: standardEnum: [ standard, sumOfProbabilities ] | ||||||||||||||||||||||||||||||||||
threeFourMismatchSortBy | string nullable: true default: resolutionScoreEnum: [ none, resolutionScore, standard (not yet available) ] | ||||||||||||||||||||||||||||||||||
secondarySortBy | string nullable: true default: tncCountEnum: [ tncCount, cd34Count ] |
Response
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 | ||||||||||||||||||
|
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 | ||||||||||||||||||||
|
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 | ||||||||||||||||||
|
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 | ||||||||||||||||||
|
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} | ||||||||||||||||||||||||||||
|
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} | ||||||||||||||||||||||||||||
|
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 | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
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 | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
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.
PlantUML Macro | ||
---|---|---|
| ||
@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/{wmdaId};
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
|
4.6 - Full report - CBUs
The retrieveFullReportCBUs endpoint is used to retrieve all available information for a specific CBU in a search result.
...
Request
...
integer
Unique identifier of the search. Can be determined by retrieving patient search summary
Response
searchId | integer nullable: false minimum: 1 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
searchType | string Enum: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
matchDuration | integer minimum: 0 nullable: true example: 30 time in seconds that the search took to run on the matching engine | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
patient |
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cbu |
|
4.7 - Suggested use of API endpoints
Below is a diagram indicated 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.
...