--- title: "Create Trial Matcher job" method: POST path: "/trialmatcher/jobs" tags: ["TrialMatcher"] --- # Create Trial Matcher job `POST /trialmatcher/jobs` ## Request - Base URL: `{endpoint}/healthinsights` - URL: `{endpoint}/healthinsights/trialmatcher/jobs` - Auth: API key in header `Ocp-Apim-Subscription-Key` Creates a Trial Matcher job with the given request body. ## Query parameters - `api-version` string, required ## Headers - `Repeatability-Request-ID` string - `Repeatability-First-Sent` string, date-time ## Request body - TrialMatcherData: The body of the Trial Matcher request. - `patients` PatientRecord[], required: The list of patients, including their clinical information and data. - `id` string, required: A given identifier for the patient. Has to be unique across all patients in a single request. - `info` PatientInfo: Patient structured information, including demographics and known structured clinical information. - `sex` 'female' | 'male' | 'unspecified': The patient's sex. - `birthDate` string, date: The patient's date of birth. - `clinicalInfo` ClinicalCodedElement[]: Known clinical information for the patient, structured. - `system` string, required: The clinical coding system, e.g. ICD-10, SNOMED-CT, UMLS. - `code` string, required: The code within the given clinical coding system. - `name` string: The name of this coded concept in the coding system. - `value` string: A value associated with the code within the given clinical coding system. - `data` PatientDocument[]: Patient unstructured clinical data, given as documents. - `type` 'note' | 'fhirBundle' | 'dicom' | 'genomicSequencing', required: The type of the patient document, such as 'note' (text document) or 'fhirBundle' (FHIR JSON document). - `clinicalType` 'consultation' | 'dischargeSummary' | 'historyAndPhysical' | 'procedure' | 'progress' | 'imaging' | 'laboratory' | 'pathology': The type of the clinical document. - `id` string, required: A given identifier for the document. Has to be unique across all documents for a single patient. - `language` string: A 2 letter ISO 639-1 representation of the language of the document. - `createdDateTime` string, date-time: The date and time when the document was created. - `content` DocumentContent, required: The content of the patient document. - `sourceType` 'inline' | 'reference', required: The type of the content's source. In case the source type is 'inline', the content is given as a string (for instance, text). In case the source type is 'reference', the content is given as a URI. - `value` string, required: The content of the document, given either inline (as a string) or as a reference (URI). - `configuration` TrialMatcherModelConfiguration: Configuration affecting the Trial Matcher model's inference. - `verbose` boolean: An indication whether the model should produce verbose output. - `includeEvidence` boolean: An indication whether the model's output should include evidence for the inferences. - `clinicalTrials` ClinicalTrials, required: The clinical trials that the patient(s) should be matched to. The trial selection can be given as a list of custom clinical trials and/or a list of filters to known clinical trial registries. In case both are given, the resulting trial set is a union of the two sets. - `customTrials` ClinicalTrialDetails[]: A list of clinical trials. - `id` string, required: A given identifier for the clinical trial. Has to be unique within a list of clinical trials. - `eligibilityCriteriaText` string: The eligibility criteria of the clinical trial (inclusion and exclusion), given as text. - `demographics` ClinicalTrialDemographics: Demographic criteria for a clinical trial. - `acceptedSex` 'all' | 'female' | 'male': Possible values for the Sex eligibility criterion as accepted by clinical trials, which indicates the sex of people who may participate in a clinical study. - `acceptedAgeRange` AcceptedAgeRange: A definition of the range of ages accepted by a clinical trial. Contains a minimum age and/or a maximum age. - `minimumAge` AcceptedAge: A person's age, given as a number (value) and a unit (e.g. years, months) - … - `maximumAge` AcceptedAge: A person's age, given as a number (value) and a unit (e.g. years, months) - … - `metadata` ClinicalTrialMetadata, required: Trial data which is of interest to the potential participant. - `phases` ClinicalTrialPhase[]: Phases which are relevant for the clinical trial. Each clinical trial can be in a certain phase or in multiple phases. - `studyType` 'interventional' | 'observational' | 'expandedAccess' | 'patientRegistries': Possible study types of a clinical trial. - `recruitmentStatus` 'unknownStatus' | 'notYetRecruiting' | 'recruiting' | 'enrollingByInvitation': Possible recruitment status of a clinical trial. - `conditions` string[], required: Medical conditions and their synonyms which are relevant for the clinical trial, given as strings. - `sponsors` string[]: Sponsors/collaborators involved with the trial. - `contacts` ContactDetails[]: Contact details of the trial administrators, for patients that want to participate in the trial. - `name` string: The person's name. - `email` string: The person's email. - `phone` string: A person's phone number. - `facilities` ClinicalTrialResearchFacility[]: Research facilities where the clinical trial is conducted. - `name` string, required: The facility's name. - `city` string: City name. - `state` string: State name. - `countryOrRegion` string, required: Country/region name. - `registryFilters` ClinicalTrialRegistryFilter[]: A list of filters, each one creating a selection of trials from a given clinical trial registry. - `conditions` string[]: Trials with any of the given medical conditions will be included in the selection (provided that other limitations are satisfied). Leaving this list empty will not limit the medical conditions. - `studyTypes` ClinicalTrialStudyType[]: Trials with any of the given study types will be included in the selection (provided that other limitations are satisfied). Leaving this list empty will not limit the study types. - `recruitmentStatuses` ClinicalTrialRecruitmentStatus[]: Trials with any of the given recruitment statuses will be included in the selection (provided that other limitations are satisfied). Leaving this list empty will not limit the recruitment statuses. - `sponsors` string[]: Trials with any of the given sponsors will be included in the selection (provided that other limitations are satisfied). Leaving this list empty will not limit the sponsors. - `phases` ClinicalTrialPhase[]: Trials with any of the given phases will be included in the selection (provided that other limitations are satisfied). Leaving this list empty will not limit the phases. - `purposes` ClinicalTrialPurpose[]: Trials with any of the given purposes will be included in the selection (provided that other limitations are satisfied). Leaving this list empty will not limit the purposes. - `ids` string[]: Trials with any of the given identifiers will be included in the selection (provided that other limitations are satisfied). Leaving this list empty will not limit the trial identifiers. - `sources` ClinicalTrialSource[]: Trials with any of the given sources will be included in the selection (provided that other limitations are satisfied). Leaving this list empty will not limit the sources. - `facilityNames` string[]: Trials with any of the given facility names will be included in the selection (provided that other limitations are satisfied). Leaving this list empty will not limit the trial facility names. - `facilityLocations` GeographicLocation[]: Trials with any of the given facility locations will be included in the selection (provided that other limitations are satisfied). Leaving this list empty will not limit the trial facility locations. - `city` string: City name. - `state` string: State name. - `countryOrRegion` string, required: Country/region name. - `facilityAreas` GeographicArea[]: Trials with any of the given facility area boundaries will be included in the selection (provided that other limitations are satisfied). Leaving this list empty will not limit the trial facility area boundaries. - `type` 'Feature', required: `GeoJSON` type. - `geometry` AreaGeometry, required: `GeoJSON` geometry, representing the area circle's center. - `type` 'Point', required: `GeoJSON` geometry type. - `coordinates` number[], required: Coordinates of the area circle's center, represented according to the `GeoJSON` standard. This is an array of 2 decimal numbers, longitude and latitude (precisely in this order). - `properties` AreaProperties, required: `GeoJSON` object properties. - `subType` 'Circle', required: `GeoJSON` object sub-type. - `radius` number, double, required: The radius of the area's circle, in meters. ## Response `200` The request has succeeded. - TrialMatcherResult: The response for the Trial Matcher request. - `jobId` string, uuid, required: Universally Unique Identifier - `createdDateTime` string, date-time, required: The date and time when the processing job was created. - `expirationDateTime` string, date-time, required: The date and time when the processing job is set to expire. - `lastUpdateDateTime` string, date-time, required: The date and time when the processing job was last updated. - `status` 'notStarted' | 'running' | 'succeeded' | 'failed' | 'partiallyCompleted', required: The status of the processing job. - `errors` AzureCoreFoundationsError[]: An array of errors, if any errors occurred during the processing job. - `code` string, required: One of a server-defined set of error codes. - `message` string, required: A human-readable representation of the error. - `target` string: The target of the error. - `details` AzureCoreFoundationsError[]: An array of details about specific errors that led to this reported error. - `innererror` AzureCoreFoundationsInnerError: An object containing more specific information about the error. As per Microsoft One API guidelines - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses. - `code` string: One of a server-defined set of error codes. - `innererror` AzureCoreFoundationsInnerError (recursive) - `results` TrialMatcherResults: The inference results for the Trial Matcher request. - `patients` TrialMatcherPatientResult[], required: Results for the patients given in the request. - `id` string, required: The identifier given for the patient in the request. - `inferences` TrialMatcherInference[], required: The model's inferences for the given patient. - `type` 'trialEligibility', required: The type of the Trial Matcher inference. - `value` string, required: The value of the inference, as relevant for the given inference type. - `description` string: The description corresponding to the inference value. - `confidenceScore` number, float: Confidence score for this inference. - `evidence` TrialMatcherInferenceEvidence[]: The evidence corresponding to the inference value. - `eligibilityCriteriaEvidence` string: A piece of evidence from the eligibility criteria text of a clinical trial. - `patientDataEvidence` ClinicalNoteEvidence: A piece of evidence from a clinical note (text document). - `id` string, required: The identifier of the document containing the evidence. - `text` string: The actual text span which is evidence for the inference. - `offset` integer, required: The start index of the evidence text span in the document (0 based). - `length` integer, required: The length of the evidence text span. - `patientInfoEvidence` ClinicalCodedElement: A piece of clinical information, expressed as a code in a clinical coding system. - `system` string, required: The clinical coding system, e.g. ICD-10, SNOMED-CT, UMLS. - `code` string, required: The code within the given clinical coding system. - `name` string: The name of this coded concept in the coding system. - `value` string: A value associated with the code within the given clinical coding system. - `importance` number, float: A value indicating how important this piece of evidence is for the inference. - `id` string: The identifier of the clinical trial. - `source` 'custom' | 'clinicaltrials.gov': Possible sources of a clinical trial. - `metadata` ClinicalTrialMetadata: Trial data which is of interest to the potential participant. - `phases` ClinicalTrialPhase[]: Phases which are relevant for the clinical trial. Each clinical trial can be in a certain phase or in multiple phases. - `studyType` 'interventional' | 'observational' | 'expandedAccess' | 'patientRegistries': Possible study types of a clinical trial. - `recruitmentStatus` 'unknownStatus' | 'notYetRecruiting' | 'recruiting' | 'enrollingByInvitation': Possible recruitment status of a clinical trial. - `conditions` string[], required: Medical conditions and their synonyms which are relevant for the clinical trial, given as strings. - `sponsors` string[]: Sponsors/collaborators involved with the trial. - `contacts` ContactDetails[]: Contact details of the trial administrators, for patients that want to participate in the trial. - `name` string: The person's name. - `email` string: The person's email. - `phone` string: A person's phone number. - `facilities` ClinicalTrialResearchFacility[]: Research facilities where the clinical trial is conducted. - `name` string, required: The facility's name. - `city` string: City name. - `state` string: State name. - `countryOrRegion` string, required: Country/region name. - `neededClinicalInfo` ExtendedClinicalCodedElement[]: Clinical information which is needed to provide better trial matching results for the patient. - `system` string, required: The clinical coding system, e.g. ICD-10, SNOMED-CT, UMLS. - `code` string, required: The code within the given clinical coding system. - `name` string: The name of this coded concept in the coding system. - `value` string: A value associated with the code within the given clinical coding system. - `semanticType` string: The [UMLS semantic type](https://www.nlm.nih.gov/research/umls/META3_current_semantic_types.html) associated with the coded concept. - `category` string: The bio-medical category related to the coded concept, e.g. Diagnosis, Symptom, Medication, Examination. - `modelVersion` string, required: The version of the model used for inference, expressed as the model date. - `knowledgeGraphLastUpdateDate` string, date: The date when the clinical trials knowledge graph was last updated. ## Other responses - `202`: The request has been accepted for processing, but processing has not yet completed. - `default`: An unexpected error response. --- [API](https://skmtc.dev/azure/apis/azure-health-insights.md) - [All operations](https://skmtc.dev/azure/apis/azure-health-insights/llms.txt) - [OpenAPI document](https://skmtc.dev/azure/apis/azure-health-insights/revisions/170d7819ac4c?raw)