Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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

searches

Expand
titleRequest...
FieldDetails
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: DR
Enum:
Array [ 2 ]
overallMismatchesinteger
default: 0
Enum:
Array [ 8 ]
lociToBeConsidered[...]
isCbuAbLowDrb1HighResolutionboolean
default: false

nullable: true
Expand
titleResponse
FieldDetails
searchIdinteger
nullable: false

minimum: 1
Send
startSearch
  • wmdaId
  • matchEngine
  • searchType
  • overallMismatches
  • cbuABLowDrb1HighResolution

    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. 

    ...

    • searchId

    4.3 - Search results - Donors

    The retrieveSearchResultsDonors endpoint is used to retrieve search results for donors. Pagination is possible and optional filters can be provided. 

    ...

    • searchId

    4.4 - Full report - Donors

    The retrieveFullReportDonors endpoint is used to retrieve all available information for a specific donor in a search result. 

    Get
    searches/{searchId}
    Expand
    titleRequest
    FieldDetails
    searchId*

    integer

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

    Expand
    titleResponse
    FieldDetails
    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: 0
    Enum:
    Array [ 8 ]
    status*string
    nullable: false
    Enum:
    Array [ 3 ]
    summary*{...}
    inexplicable*integer
    nullable: true

    Total number of donors whose phenotype cannot be explained by known haplotype

    statistics*{...}
    error*{...}
    nullable: true
    lociToBeConsidered[...]
    lastUpdatedstring($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}
    Expand
    titleRequest
    FieldDetails
    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.

    Expand
    titleResponse
    FieldDetails
    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: 0
    Enum:
    Array [ 8 ]
    status*string
    nullable: false
    Enum:
    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

    inexplicableinteger
    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
    Expand
    titleRequest
    FieldDetails
    pagination{...}
    searchId*integer
    nullable: false

    minimum: 1
    filters{...}
    sortBy

    string
    nullable: true

    default: standard
    Enum:
    Array [ 2 ]

    Expand
    titleResponse
    FieldDetails
    paging*{...}
    searchResults*[...]
    Send
    retrieveSearchResultsDonors
    searchResultsId

    4.5 - Search results - CBUs

    The A POST to the searches/searchResults/cbus retrieveSearchResultsDonors endpoint is used to retrieve search results for 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
    Expand
    titleRequest
    FieldDetails
    pagination{...}
    searchId*integer
    nullable: false

    minimum: 1
    filters{...}
    sortBystring
    nullable: true

    default: standard
    Enum:
    Array [ 2 ]
    threeFourMismatchSortBystring
    nullable: true

    default: resolutionScore
    Enum:
    Array [ 3 ]
    secondarySortBystring
    nullable: true

    default: 

    ...

    • searchId

    4.6 - Full report - CBUs

    tncCountEnum:
    Array [ 2 ]
    Expand
    titleResponse
    FieldDetails
    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
    Expand
    titleRequest
    FieldDetails
    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.

    gridstring
    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

    Expand
    titleResponse
    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
    Expand
    titleRequest
    FieldDetails
    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.

    donorRegistryIoninteger
    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

    Expand
    titleResponse
    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
    Expand
    titleRequest
    FieldDetails
    searchId*

    integer

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

    Expand
    titleResponse
    FieldDetails
    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
    Expand
    titleRequest
    FieldDetails
    searchId*

    integer

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

    Expand
    titleResponse
    FieldDetails
    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}
    Expand
    titleRequest
    FieldDetails
    searchResultsId*

    integer

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

    Expand
    titleResponse
    FieldDetails
    searchIdinteger
    nullable: false

    minimum: 1
    searchTypestring
    Enum:
    Array [ 1 ]
    matchDurationinteger
    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 The retrieveFullReportCBUs endpoint is used to retrieve all available information for a specific CBU in a search result. 

    ...

    • searchResultsId

    ...

    Get
    searches/cbus/{searchResultsId}
    Expand
    titleRequest
    Field

    Details

    searchResultsId*

    integer

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

    Expand
    titleResponse
    FieldDetails
    searchIdinteger
    nullable: false

    minimum: 1
    searchTypestringEnum:
    Array [ 1 ]
    matchDurationinteger
    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

    Expand
    titleRequest...
    FieldDetails
    wmdaId*integer
    example: 123456

    nullable: false
    Expand
    titleResponse
    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

    Expand
    titleRequest...
    FieldDetails
    searchId*integer
    example: 123456

    nullable: false
    Expand
    titleResponse
    FieldDetails
    newSearchIdinteger
    example: 123457

    nullable: false

    4.14 - Suggested use of API endpoints

    Below is a diagram indicated 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. Image Removed

    PlantUML Macro
    titleSuggested use of API endpoints
    @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