Quickstart: Use the Trial Matcher model

This quickstart provides an overview on how to use the Trial Matcher.

Prerequisites

To use Trial Matcher, you must have an Azure AI services account created. If you haven't already created an Azure AI services account, see Deploy Azure AI Health Insights using the Azure portal.

Once deployment is complete, you use the Azure portal to navigate to the newly created Azure AI services account to see the details, including your Service URL. The Service URL to access your service is: https://YOUR-NAME.cognitiveservices.azure.com/.

Submit a request and get results

To send an API request, you need your Azure AI services account endpoint and key.

Important

The Trial Matcher is an asynchronous API. Trial Matcher prediction is performed upon receipt of the API request and the results are returned asynchronously. The API results are available for 24 hours from the time the request was ingested and is indicated in the response. After the time period, the results are purged and are no longer available for retrieval.

Example Request

To submit a request to the Trial Matcher, you need to make a POST request to the endpoint.

In the example below the patients are matches to the Clinicaltrials_gov source, for a lung cancer condition with facility locations for the city Orlando.

POST https://{your-cognitive-service-endpoint}/healthinsights/trialmatcher/jobs?api-version=2022-01-01-preview
Content-Type: application/json
Ocp-Apim-Subscription-Key: {your-cognitive-services-api-key}
{
    "Configuration": {
        "ClinicalTrials": {
            "RegistryFilters": [
                {
                    "Sources": [
                        "Clinicaltrials_gov"
                    ],
                    "Conditions": ["lung cancer"],
                    "facilityLocations": [
                        {
                            "State": "FL",
                            "City": "Orlando",
                            "countryOrRegion": "United States"
                        }
                    ]
                }
            ]
        },
        "IncludeEvidence": false,
        "Verbose": false
    },
    "Patients": [
        {
            "Info": {
                "sex": "female",
                "birthDate": "01/01/1987",
                "ClinicalInfo": [
                    
                ]
            },
            "id": "12"
        }
    ]
}

You can also find a full view of the request parameters here

The response includes the operation-location in the response header. The value looks similar to the following URL: https://eastus.api.cognitive.microsoft.com/healthinsights/trialmatcher/jobs/b58f3776-c6cb-4b19-a5a7-248a0d9481ff?api_version=2022-01-01-preview

Example Response

To get the results of the request, make the following GET request to the URL specified in the POST response operation-location header.

GET https://{your-cognitive-service-endpoint}/healthinsights/trialmatcher/jobs/{job-id}?api-version=2022-01-01-preview
Content-Type: application/json
Ocp-Apim-Subscription-Key: {your-cognitive-services-api-key}

An example response:

{
    "results": {
        "patients": [
            {
                "id": "12",
                "inferences": [
                    {
                        "type": "trialEligibility",
                        "id": "NCT03318939",
                        "source": "clinicaltrials.gov",
                        "value": "Eligible"
                    },
                    {
                        "type": "trialEligibility",
                        "id": "NCT03417882",
                        "source": "clinicaltrials.gov",
                        "value": "Eligible"
                    },
                    {
                        "type": "trialEligibility",
                        "id": "NCT02628067",
                        "source": "clinicaltrials.gov",
                        "value": "Eligible"
                    },
                    {
                        "type": "trialEligibility",
                        "id": "NCT04948554",
                        "source": "clinicaltrials.gov",
                        "value": "Eligible"
                    },
                    {
                        "type": "trialEligibility",
                        "id": "NCT04616924",
                        "source": "clinicaltrials.gov",
                        "value": "Eligible"
                    },
                    {
                        "type": "trialEligibility",
                        "id": "NCT04504916",
                        "source": "clinicaltrials.gov",
                        "value": "Eligible"
                    },
                    {
                        "type": "trialEligibility",
                        "id": "NCT02635009",
                        "source": "clinicaltrials.gov",
                        "value": "Eligible"
                    },
                    ...
                ],
                "neededClinicalInfo": [
                    {
                        "system": "http://www.nlm.nih.gov/research/umls",
                        "code": "METASTATIC",
                        "name": "metastatic"
                    },
                    {
                        "semanticType": "T000",
                        "system": "http://www.nlm.nih.gov/research/umls",
                        "code": "C0032961",
                        "name": "Pregnancy"
                    },
                    {
                        "semanticType": "T000",
                        "system": "http://www.nlm.nih.gov/research/umls",
                        "code": "C1512162",
                        "name": "Eastern Cooperative Oncology Group"
                    }
                ]
            }
        ],
        "modelVersion": "2022.03.24",
        "knowledgeGraphLastUpdateDate": "2022.03.29"
    },
    "jobId": "26484d27-f5d7-4c74-a078-a359d1634a63",
    "createdDateTime": "2022-04-04T16:56:00Z",
    "expirationDateTime": "2022-04-04T17:56:00Z",
    "lastUpdateDateTime": "2022-04-04T16:56:00Z",
    "status": "succeeded"
}

You can also find a full view of the response parameters here

Data limits

Limit	Value
Maximum # patients per request	1
Maximum # trials per patient	5000
Maximum # location filter per request	1

Next steps

To get better insights into the request and responses, read more on the following pages:

Model configuration

Patient information