Onco Phenotype - Create Job

Service:

Cognitive Services

API Version:

2023-09-01-preview

Create Onco Phenotype job
Creates an Onco Phenotype job with the given request body.

POST {endpoint}/health-insights/onco-phenotype/jobs?api-version=2023-09-01-preview

URI Parameters

Name	In	Required	Type	Description
endpoint	path	True	string uri	Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus2.api.cognitive.microsoft.com).
api-version	query	True	string	The API version to use for this operation.

Request Header

Name	Required	Type	Description
Ocp-Apim-Subscription-Key	True	string
Repeatability-Request-ID		string	An opaque, globally-unique, client-generated string identifier for the request.
Repeatability-First-Sent		string date-time	Specifies the date and time at which the request was first created.

Request Body

Name	Required	Type	Description
patients	True	PatientRecord[]	The list of patients, including their clinical information and data.
configuration		OncoPhenotypeModelConfiguration	Configuration affecting the Onco Phenotype model's inference.

Responses

Name	Type	Description
202 Accepted		The request has been accepted for processing, but processing has not yet completed. Headers Operation-Location: string Repeatability-Result: string Retry-After: integer
Other Status Codes	Azure.Core.Foundations.ErrorResponse	An unexpected error response. Headers x-ms-error-code: string

Security

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

Examples

Creates an Onco Phenotype job with the given request body.

Sample request

HTTP

POST {endpoint}/health-insights/onco-phenotype/jobs?api-version=2023-09-01-preview

{
  "patients": [
    {
      "id": "Patient ID Example 1",
      "info": {
        "sex": "female",
        "birthDate": "1975-09-27"
      },
      "patientDocuments": [
        {
          "type": "note",
          "clinicalType": "historyAndPhysical",
          "id": "1",
          "language": "en",
          "createdDateTime": "2021-10-26T16:54:44.739Z",
          "content": {
            "sourceType": "inline",
            "value": "Sample note 1"
          }
        },
        {
          "type": "note",
          "clinicalType": "imaging",
          "id": "2",
          "language": "en",
          "createdDateTime": "2020-11-26T16:39:44.739Z",
          "content": {
            "sourceType": "inline",
            "value": "Sample note 2"
          }
        }
      ]
    }
  ],
  "configuration": {
    "verbose": true,
    "includeEvidence": true,
    "inferenceTypes": [
      "histology",
      "clinicalStageT"
    ],
    "checkForCancerCase": false
  }
}

Sample response

Status code:

202

Operation-Location: {endpoint}/health-insights/onco-phenotype/jobs/{id}?api-version=2023-09-01-preview
Retry-After: 1

{
  "status": "notStarted",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Definitions

Name	Description
Azure.Core.Foundations.Error	The error object.
Azure.Core.Foundations.ErrorResponse	A response containing error details.
Azure.Core.Foundations.InnerError	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.
ClinicalDocumentType	The type of the clinical document.
DocumentAdministrativeMetadata	Document administrative metadata
DocumentAuthor	Document author
DocumentContent	The content of the patient document.
DocumentContentSourceType	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.
DocumentType	The type of the patient document, such as 'note' (text document) or 'fhirBundle' (FHIR JSON document).
Encounter	visit/encounter information
EncounterClass	Known values codes that can be used to indicate the class of encounter (TODO://Based on FHIR value set--http://....).
Fhir.R4.CodeableConcept	Concept - reference to a terminology or just text Based on FHIR CodeableConcept
Fhir.R4.Coding	A Coding is a representation of a defined concept using a symbol from a defined "code system". Based on FHIR Coding
Fhir.R4.Extension	Base for all elements Based on FHIR Element
Fhir.R4.Identifier	An identifier intended for computation Based on FHIR Identifier
Fhir.R4.Meta	Metadata about a resource Based on FHIR Meta
Fhir.R4.Period	A time period defined by a start and end date and optionally time Based on FHIR Period
Fhir.R4.Quantity	A measured or measurable amount Based on FHIR Quantity
Fhir.R4.Range	A set of ordered Quantities defined by a low and high limit Based on FHIR Range
Fhir.R4.Ratio	A ratio of two Quantity values - a numerator and a denominator Based on FHIR Ratio
Fhir.R4.Reference	A reference from one resource to another Based on FHIR Reference
Fhir.R4.Resource	Resource is the ancestor of DomainResource from which most resources are derived. Bundle, Parameters, and Binary extend Resource directly. Based on [FHIR Resource](https://www.hl7.org/fhir/r4/resource.html
Fhir.R4.SampledData	A series of measurements taken by a device Based on FHIR SampledData
OncoPhenotypeData	The body of the Onco Phenotype request.
OncoPhenotypeInferenceType	The type of the Onco Phenotype inference.
OncoPhenotypeModelConfiguration	Configuration affecting the Onco Phenotype model's inference.
OrderedProcedure	Procedure information
PatientDocument	A clinical document related to a patient. Document here is in the wide sense - not just a text document (note).
PatientInfo	Patient structured information, including demographics and known structured clinical information.
PatientInfoSex	The patient's sex.
PatientRecord	A patient record, including their clinical information and data.
SpecialtyType	Known values codes that can be used to indicate the type of the Specialty.
TimePeriod	A duration of time during which an event is happening

Azure.Core.Foundations.Error

The error object.

Name	Type	Description
code	string	One of a server-defined set of error codes.
details	Azure.Core.Foundations.Error[]	An array of details about specific errors that led to this reported error.
innererror	Azure.Core.Foundations.InnerError	An object containing more specific information than the current object about the error.
message	string	A human-readable representation of the error.
target	string	The target of the error.

Azure.Core.Foundations.ErrorResponse

A response containing error details.

Name	Type	Description
error	Azure.Core.Foundations.Error	The error object.

Azure.Core.Foundations.InnerError

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.

Name	Type	Description
code	string	One of a server-defined set of error codes.
innererror	Azure.Core.Foundations.InnerError	Inner error.

ClinicalDocumentType

The type of the clinical document.

Name	Type	Description
consultation	string
dischargeSummary	string
historyAndPhysical	string
laboratory	string
pathologyReport	string
procedure	string
progress	string
radiologyReport	string

DocumentAdministrativeMetadata

Document administrative metadata

Name	Type	Description
encounterId	string	Reference to the encounter associated with the document.
orderedProcedures	OrderedProcedure[]	List of procedure information associated with the document.

DocumentAuthor

Document author

Name	Type	Description
fullName	string	Text representation of the full name
id	string	author id

DocumentContent

The content of the patient document.

Name	Type	Description
sourceType	DocumentContentSourceType	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	The content of the document, given either inline (as a string) or as a reference (URI).

DocumentContentSourceType

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.

Name	Type	Description
inline	string	The content is given as a string (for instance, text).
reference	string	The content is given as a URI.

DocumentType

The type of the patient document, such as 'note' (text document) or 'fhirBundle' (FHIR JSON document).

Name	Type	Description
dicom	string
fhirBundle	string
genomicSequencing	string
note	string

Encounter

visit/encounter information

Name	Type	Description
class	EncounterClass	The class of the encounter.
id	string	The id of the visit.
period	TimePeriod	Time period of the visit. In case of admission, use timePeriod.start to indicate the admission time and timePeriod.end to indicate the discharge time.

EncounterClass

Known values codes that can be used to indicate the class of encounter (TODO://Based on FHIR value set--http://....).

Name	Type	Description
ambulatory	string	The term ambulatory usually implies that the patient has come to the location and is not assigned to a bed. Sometimes referred to as an outpatient encounter.
emergency	string	A patient encounter that takes place at a dedicated healthcare service delivery location where the patient receives immediate evaluation and treatment, provided until the patient can be discharged or responsibility for the patient's care is transferred elsewhere (for example, the patient could be admitted as an inpatient or transferred to another facility.
healthHome	string	Healthcare encounter that takes place in the residence of the patient or a designee
inpatient	string	A patient encounter where a patient is admitted by a hospital or equivalent facility, assigned to a location where patients generally stay at least overnight and provided with room, board, and continuous nursing service.
observation	string	An encounter where the patient usually will start in different encounter, such as one in the emergency department but then transition to this type of encounter because they require a significant period of treatment and monitoring to determine whether or not their condition warrants an inpatient admission or discharge.
virtual	string	A patient encounter where the patient is not physically present for the encounter, such as in a telehealth encounter, phone call, or electronic communication.

Fhir.R4.CodeableConcept

Concept - reference to a terminology or just text Based on FHIR CodeableConcept

Name	Type	Description
coding	Fhir.R4.Coding[]	Code defined by a terminology system
extension	Fhir.R4.Extension[]	Additional Content defined by implementations
id	string	Unique id for inter-element referencing
text	string	Plain text representation of the concept

Fhir.R4.Coding

A Coding is a representation of a defined concept using a symbol from a defined "code system". Based on FHIR Coding

Name	Type	Description
code	string	Symbol in syntax defined by the system
display	string	Representation defined by the system
extension	Fhir.R4.Extension[]	Additional Content defined by implementations
id	string	Unique id for inter-element referencing
system	string	Identity of the terminology system
version	string	Version of the system - if relevant

Fhir.R4.Extension

Base for all elements Based on FHIR Element

Name	Type	Description
extension	Fhir.R4.Extension[]	Additional Content defined by implementations
id	string	Unique id for inter-element referencing
url	string	Source of the definition for the extension code - a logical name or a URL.
valueBoolean	boolean	Value as boolean
valueCodeableConcept	Fhir.R4.CodeableConcept	Value as CodeableConcept
valueDateTime	string	Value as dateTime.
valueInteger	integer	Value as integer
valuePeriod	Fhir.R4.Period	Value as Period.
valueQuantity	Fhir.R4.Quantity	Value as Quantity
valueRange	Fhir.R4.Range	Value as Range.
valueRatio	Fhir.R4.Ratio	Value as Ratio.
valueReference	Fhir.R4.Reference	Value as reference.
valueSampledData	Fhir.R4.SampledData	Value as SampledData.
valueString	string	Value as string
valueTime	string	Value as time (hh:mm:ss)

Fhir.R4.Identifier

An identifier intended for computation Based on FHIR Identifier

Name	Type	Description
assigner	Fhir.R4.Reference	Organization that issued id (may be just text)
extension	Fhir.R4.Extension[]	Additional Content defined by implementations
id	string	Unique id for inter-element referencing
period	Fhir.R4.Period	Time period when id is/was valid for use
system	string	The namespace for the identifier value
type	Fhir.R4.CodeableConcept	Description of identifier
use	string	usual | official | temp | secondary | old (If known)
value	string	The value that is unique

Fhir.R4.Meta

Metadata about a resource Based on FHIR Meta

Name	Type	Description
lastUpdated	string	When the resource last changed - e.g. when the version changed.
profile	string[]	A list of profiles (references to StructureDefinition resources) that this resource claims to conform to. The URL is a reference to StructureDefinition.url.
security	Fhir.R4.Coding[]	Security labels applied to this resource. These tags connect specific resources to the overall security policy and infrastructure.
source	string	A uri that identifies the source system of the resource. This provides a minimal amount of Provenance information that can be used to track or differentiate the source of information in the resource. The source may identify another FHIR server, document, message, database, etc.
tag	Fhir.R4.Coding[]	Tags applied to this resource. Tags are intended to be used to identify and relate resources to process and workflow, and applications are not required to consider the tags when interpreting the meaning of a resource.
versionId	string	The version specific identifier, as it appears in the version portion of the URL. This value changes when the resource is created, updated, or deleted.

Fhir.R4.Period

A time period defined by a start and end date and optionally time Based on FHIR Period

Name	Type	Description
end	string	End time with inclusive boundary, if not ongoing
extension	Fhir.R4.Extension[]	Additional Content defined by implementations
id	string	Unique id for inter-element referencing
start	string	Starting time with inclusive boundary

Fhir.R4.Quantity

A measured or measurable amount Based on FHIR Quantity

Name	Type	Description
code	string	Coded form of the unit
comparator	string	< | <= | >= | > - how to understand the value
extension	Fhir.R4.Extension[]	Additional Content defined by implementations
id	string	Unique id for inter-element referencing
system	string	System that defines coded unit form
unit	string	Unit representation
value	number	Numerical value (with implicit precision)

Fhir.R4.Range

A set of ordered Quantities defined by a low and high limit Based on FHIR Range

Name	Type	Description
extension	Fhir.R4.Extension[]	Additional Content defined by implementations
high	Fhir.R4.Quantity	High limit
id	string	Unique id for inter-element referencing
low	Fhir.R4.Quantity	Low limit

Fhir.R4.Ratio

A ratio of two Quantity values - a numerator and a denominator Based on FHIR Ratio

Name	Type	Description
denominator	Fhir.R4.Quantity	Denominator value
extension	Fhir.R4.Extension[]	Additional Content defined by implementations
id	string	Unique id for inter-element referencing
numerator	Fhir.R4.Quantity	Numerator value

Fhir.R4.Reference

A reference from one resource to another Based on FHIR Reference

Name	Type	Description
display	string	Text alternative for the resource
extension	Fhir.R4.Extension[]	Additional Content defined by implementations
id	string	Unique id for inter-element referencing
identifier	Fhir.R4.Identifier	Logical reference, when literal reference is not known
reference	string	Literal reference, Relative, internal or absolute URL
type	string	Type the reference refers to (e.g. "Patient")

Fhir.R4.Resource

Resource is the ancestor of DomainResource from which most resources are derived. Bundle, Parameters, and Binary extend Resource directly. Based on [FHIR Resource](https://www.hl7.org/fhir/r4/resource.html

Name	Type	Description
id	string	Resource Id
implicitRules	string	A set of rules under which this content was created
language	string	Language of the resource content
meta	Fhir.R4.Meta	Metadata about the resource
resourceType	string	The type of resource

Fhir.R4.SampledData

A series of measurements taken by a device Based on FHIR SampledData

Name	Type	Description
data	string	Decimal values with spaces, or "E" | "U" | "L"
dimensions	integer	Number of sample points at each time point
extension	Fhir.R4.Extension[]	Additional Content defined by implementations
factor	number	Multiply data by this before adding to origin
id	string	Unique id for inter-element referencing
lowerLimit	number	Lower limit of detection
origin	Fhir.R4.Quantity	Zero value and units
period	number	Number of milliseconds between samples
upperLimit	number	Upper limit of detection

OncoPhenotypeData

The body of the Onco Phenotype request.

Name	Type	Description
configuration	OncoPhenotypeModelConfiguration	Configuration affecting the Onco Phenotype model's inference.
patients	PatientRecord[]	The list of patients, including their clinical information and data.

OncoPhenotypeInferenceType

The type of the Onco Phenotype inference.

Name	Type	Description
clinicalStageM	string
clinicalStageN	string
clinicalStageT	string
diagnosisDate	string
histology	string
pathologicStageM	string
pathologicStageN	string
pathologicStageT	string
tumorSite	string

OncoPhenotypeModelConfiguration

Configuration affecting the Onco Phenotype model's inference.

Name	Type	Default value	Description
checkForCancerCase	boolean	False	An indication whether to perform a preliminary step on the patient's documents to determine whether they relate to a Cancer case.
includeEvidence	boolean	True	An indication whether the model's output should include evidence for the inferences.
inferenceTypes	OncoPhenotypeInferenceType[]		A list of inference types to be inferred for the current request. This could be used if only part of the Onco Phenotype inferences are required. If this list is omitted or empty, the model will return all the inference types.
verbose	boolean	False	An indication whether the model should produce verbose output.

OrderedProcedure

Procedure information

Name	Type	Description
code	Fhir.R4.CodeableConcept	Procedure code
description	string	Procedure description
extension	Fhir.R4.Extension[]	Additional Content defined by implementations

PatientDocument

A clinical document related to a patient. Document here is in the wide sense - not just a text document (note).

Name	Type	Description
administrativeMetadata	DocumentAdministrativeMetadata	Administrative metadata for the document.
authors	DocumentAuthor[]	Document author(s)
clinicalType	ClinicalDocumentType	The type of the clinical document.
content	DocumentContent	The content of the patient document.
createdDateTime	string	The date and time when the document was created.
id	string	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.
specialtyType	SpecialtyType	specialty type the document
type	DocumentType	The type of the patient document, such as 'note' (text document) or 'fhirBundle' (FHIR JSON document).

PatientInfo

Patient structured information, including demographics and known structured clinical information.

Name	Type	Description
birthDate	string	The patient's date of birth.
clinicalInfo	Fhir.R4.Resource[]	Known clinical information for the patient, structured.
sex	PatientInfoSex	The patient's sex.

PatientInfoSex

The patient's sex.

Name	Type	Description
female	string
male	string
unspecified	string

PatientRecord

A patient record, including their clinical information and data.

Name	Type	Description
encounters	Encounter[]	Patient encounters/visits.
id	string	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.
patientDocuments	PatientDocument[]	Patient unstructured clinical data, given as documents.

SpecialtyType

Known values codes that can be used to indicate the type of the Specialty.

Name	Type	Description
pathology	string	pathology
radiology	string	radiology

TimePeriod

A duration of time during which an event is happening

Name	Type	Description
end	string	End time with inclusive boundary, if not ongoing
start	string	Starting time with inclusive boundary