Analyze Text - Submit Job

Service:: Azure AI Services

API Version:: 2023-04-15-preview

Submit text analysis job
Submit a collection of text documents for analysis. Specify one or more unique tasks to be executed as a long-running operation.

POST {Endpoint}/language/analyze-text/jobs?api-version=2023-04-15-preview

URI Parameters

Name	In	Required	Type	Description
api-version	query	True	string	Client API version.

Request Body

Name	Required	Type	Description
analysisInput	True	MultiLanguageAnalysisInput
tasks	True	AnalyzeTextLROTask[]: CustomEntitiesLROTask[] CustomSingleLabelClassificationLROTask[] CustomMultiLabelClassificationLROTask[] HealthcareLROTask[] CustomHealthcareLROTask[] SentimentAnalysisLROTask[] CustomSentimentAnalysisLROTask[] EntitiesLROTask[] EntityLinkingLROTask[] PiiLROTask[] ExtractiveSummarizationLROTask[] KeyPhraseLROTask[] AbstractiveSummarizationLROTask[] CustomAbstractiveSummarizationLROTask[]	The set of tasks to execute on the input documents.
defaultLanguage		string	Default language to use for records requesting automatic language detection.
displayName		string	Optional display name for the analysis job.

Responses

Name	Type	Description
202 Accepted		A successful call results with an Operation-Location header used to check the status of the analysis job. Headers Operation-Location: string
Other Status Codes	ErrorResponse	Error response.

Name

Type

Description

202 Accepted

A successful call results with an Operation-Location header used to check the status of the analysis job.

Headers

Operation-Location: string

Other Status Codes

ErrorResponse

Error response.

Security

AADToken

These are the Azure Active Directory OAuth2 Flows. When paired with Azure role-based access control it can be used to control access to Azure Maps REST APIs. Azure role-based access controls are used to designate access to one or more Azure Maps resource account or sub-resources. Any user, group, or service principal can be granted access via a built-in role or a custom role composed of one or more permissions to Azure Maps REST APIs.

To implement scenarios, we recommend viewing authentication concepts. In summary, this security definition provides a solution for modeling application(s) via objects capable of access control on specific APIs and scopes.

Notes

This security definition requires the use of the x-ms-client-id header to indicate which Azure Maps resource the application is requesting access to. This can be acquired from the Maps management API.

The Authorization URL is specific to the Azure public cloud instance. Sovereign clouds have unique Authorization URLs and Azure Active directory configurations. * The Azure role-based access control is configured from the Azure management plane via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs. * Usage of the Azure Maps Web SDK allows for configuration based setup of an application for multiple use cases.

Currently, Azure Active Directory v1.0 or v2.0 supports Work, School, and Guests but does not support Personal accounts.

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name	Description
https://cognitiveservices.azure.com/.default	https://cognitiveservices.azure.com/.default

Ocp-Apim-Subscription-Key

A subscription key for a Language service resource.

Type: apiKey
In: header

Examples

Successful Custom Healthcare Post Request

Successful Custom Sentiment Analysis Post Request

Successful Healthcare DocumentType Post Request

Successful Healthcare Post Request

Successful Submit Abstractive Summarization Task

Successful Submit Analysis Job Request

Successful Submit Custom Abstractive Summarization Task

Successful Custom Healthcare Post Request

Sample request

HTTP

POST {Endpoint}/language/analyze-text/jobs?api-version=2023-04-15-preview

{
  "analysisInput": {
    "documents": [
      {
        "text": "Prescribed 100mg ibuprofen, taken twice daily.",
        "id": "1",
        "language": "en"
      }
    ]
  },
  "tasks": [
    {
      "kind": "CustomHealthcare",
      "parameters": {
        "projectName": "{PROJECT-NAME}",
        "deploymentName": "{DEPLOYMENT-NAME}"
      }
    }
  ]
}

Sample response

Status code:: 202

Operation-Location: {Endpoint}/language/analyze-text/jobs/{jobId}?api-version=2023-04-01

Successful Custom Sentiment Analysis Post Request

Sample request

HTTP

POST {Endpoint}/language/analyze-text/jobs?api-version=2023-04-15-preview

{
  "analysisInput": {
    "documents": [
      {
        "text": "The food is great. But the service is bad.",
        "id": "1",
        "language": "en"
      }
    ]
  },
  "tasks": [
    {
      "kind": "CustomSentimentAnalysis",
      "parameters": {
        "projectName": "{PROJECT-NAME}",
        "deploymentName": "{DEPLOYMENT-NAME}"
      }
    }
  ]
}

Sample response

Status code:: 202

Operation-Location: {Endpoint}/language/analyze-text/jobs/{jobId}?api-version=2023-04-15-preview

Successful Healthcare DocumentType Post Request

Sample request

HTTP

POST {Endpoint}/language/analyze-text/jobs?api-version=2023-04-15-preview

{
  "analysisInput": {
    "documents": [
      {
        "text": "Prescribed 100mg ibuprofen, taken twice daily.",
        "id": "1",
        "language": "en"
      }
    ]
  },
  "tasks": [
    {
      "kind": "Healthcare",
      "parameters": {
        "modelVersion": "latest",
        "fhirVersion": "4.0.1",
        "documentType": "DischargeSummary"
      }
    }
  ]
}

Sample response

Status code:: 202

Operation-Location: {Endpoint}/language/analyze-text/jobs/{jobId}?api-version=2023-04-15-preview

Successful Healthcare Post Request

Sample request

HTTP

POST {Endpoint}/language/analyze-text/jobs?api-version=2023-04-15-preview

{
  "analysisInput": {
    "documents": [
      {
        "text": "Prescribed 100mg ibuprofen, taken twice daily.",
        "id": "1",
        "language": "en"
      }
    ]
  },
  "tasks": [
    {
      "kind": "Healthcare",
      "parameters": {
        "modelVersion": "latest"
      }
    }
  ]
}

Sample response

Status code:: 202

Operation-Location: {Endpoint}/language/analyze-text/jobs/{jobId}?api-version=2023-04-15-preview

Successful Submit Abstractive Summarization Task

Sample request

HTTP

POST {Endpoint}/language/analyze-text/jobs?api-version=2023-04-15-preview

{
  "displayName": "Document Abstractive Summarization Task Example",
  "analysisInput": {
    "documents": [
      {
        "id": "1",
        "language": "en",
        "text": "At Microsoft, we have been on a quest to advance AI beyond existing techniques, by taking a more holistic, human-centric approach to learning and understanding. As Chief Technology Officer of Azure AI Cognitive Services, I have been working with a team of amazing scientists and engineers to turn this quest into a reality. In my role, I enjoy a unique perspective in viewing the relationship among three attributes of human cognition: monolingual text (X), audio or visual sensory signals, (Y) and multilingual (Z). At the intersection of all three, there is magic—what we call XYZ-code as illustrated in Figure 1—a joint representation to create more powerful AI that can speak, hear, see, and understand humans better. We believe XYZ-code will enable us to fulfill our long-term vision: cross-domain transfer learning, spanning modalities and languages. The goal is to have pre-trained models that can jointly learn representations to support a broad range of downstream AI tasks, much in the way humans do today. Over the past five years, we have achieved human performance on benchmarks in conversational speech recognition, machine translation, conversational question answering, machine reading comprehension, and image captioning. These five breakthroughs provided us with strong signals toward our more ambitious aspiration to produce a leap in AI capabilities, achieving multi-sensory and multilingual learning that is closer in line with how humans learn and understand. I believe the joint XYZ-code is a foundational component of this aspiration, if grounded with external knowledge sources in the downstream AI tasks."
      }
    ]
  },
  "tasks": [
    {
      "kind": "AbstractiveSummarization",
      "taskName": "Document Abstractive Summarization Task 1",
      "parameters": {
        "sentenceCount": 1
      }
    }
  ]
}

Sample response

Status code:: 202

Operation-Location: {endpoint}/language/analyze-text/jobs/{jobId}?api-version=2023-04-15-preview

Successful Submit Analysis Job Request

Sample request

HTTP

POST {Endpoint}/language/analyze-text/jobs?api-version=2023-04-15-preview

{
  "displayName": "Extracting Location & US Region",
  "analysisInput": {
    "documents": [
      {
        "id": "1",
        "language": "en",
        "text": "I had a wonderful trip to Seattle last week."
      },
      {
        "id": "2",
        "language": "en",
        "text": "I'm flying to NYC tomorrow. See you there."
      }
    ]
  },
  "tasks": [
    {
      "kind": "EntityRecognition",
      "taskName": "Recognize Entities",
      "parameters": {
        "modelVersion": "latest"
      }
    },
    {
      "kind": "CustomEntityRecognition",
      "taskName": "Recognize US Regions",
      "parameters": {
        "projectName": "MyProject",
        "deploymentName": "MyDeployment"
      }
    }
  ]
}

Sample response

Status code:: 202

Operation-Location: {endpoint}/language/analyze-text/jobs/{jobId}?api-version=2023-04-15-preview

Successful Submit Custom Abstractive Summarization Task

Sample request

HTTP

POST {Endpoint}/language/analyze-text/jobs?api-version=2023-04-15-preview

{
  "displayName": "Document Custom Abstractive Summarization Task Example",
  "analysisInput": {
    "documents": [
      {
        "id": "1",
        "language": "en",
        "text": "At Microsoft, we have been on a quest to advance AI beyond existing techniques, by taking a more holistic, human-centric approach to learning and understanding. As Chief Technology Officer of Azure AI Cognitive Services, I have been working with a team of amazing scientists and engineers to turn this quest into a reality. In my role, I enjoy a unique perspective in viewing the relationship among three attributes of human cognition: monolingual text (X), audio or visual sensory signals, (Y) and multilingual (Z). At the intersection of all three, there is magic—what we call XYZ-code as illustrated in Figure 1—a joint representation to create more powerful AI that can speak, hear, see, and understand humans better. We believe XYZ-code will enable us to fulfill our long-term vision: cross-domain transfer learning, spanning modalities and languages. The goal is to have pre-trained models that can jointly learn representations to support a broad range of downstream AI tasks, much in the way humans do today. Over the past five years, we have achieved human performance on benchmarks in conversational speech recognition, machine translation, conversational question answering, machine reading comprehension, and image captioning. These five breakthroughs provided us with strong signals toward our more ambitious aspiration to produce a leap in AI capabilities, achieving multi-sensory and multilingual learning that is closer in line with how humans learn and understand. I believe the joint XYZ-code is a foundational component of this aspiration, if grounded with external knowledge sources in the downstream AI tasks."
      }
    ]
  },
  "tasks": [
    {
      "kind": "CustomAbstractiveSummarization",
      "taskName": "Custom Document Abstractive Summarization Task 1",
      "parameters": {
        "projectName": "my_project",
        "deploymentName": "my_deployment"
      }
    }
  ]
}

Sample response

Status code:: 202

Operation-Location: {endpoint}/language/analyze-text/jobs/{jobId}?api-version=2023-04-15-preview

Definitions

Name	Description
AbstractiveSummarizationLROTask	An object representing the task definition for an Abstractive Summarization task.
AbstractiveSummarizationTaskParameters	Supported parameters for the pre-build Abstractive Summarization task.
AllowOverlapEntityPolicyType	Represents the allow overlap policy. Will apply no post processing logic for the entities. Whatever the model predicts is what will be returned to the user. This allows the user to get a full view of every single model's possible values and apply their own custom logic on entity selection
AnalyzeTextJobsInput
AnalyzeTextLROTaskKind	Enumeration of supported long-running Text Analysis tasks.
CustomAbstractiveSummarizationLROTask	An object representing the task definition for an Custom Abstractive Summarization task.
CustomAbstractiveSummarizationTaskParameters	Supported parameters for the Custom Abstractive Summarization task.
CustomEntitiesLROTask	Use custom models to ease the process of information extraction from unstructured documents like contracts or financial documents
CustomEntitiesTaskParameters	Supported parameters for a Custom Entities task.
CustomHealthcareLROTask
CustomHealthcareTaskParameters	Supported parameters for a custom Healthcare task.
CustomMultiLabelClassificationLROTask	Use custom models to classify text into multi label taxonomy
CustomMultiLabelClassificationTaskParameters	Supported parameters for a Custom Multi Classification task.
CustomSentimentAnalysisLROTask	Use custom models to ease the process of sentiment analysis from documents like product reviews
CustomSentimentAnalysisTaskParameters	Supported parameters for a Custom Sentiment Analysis task.
CustomSingleLabelClassificationLROTask	Use custom models to classify text into single label taxonomy
CustomSingleLabelClassificationTaskParameters	Supported parameters for a Custom Single Classification task.
EntitiesLROTask	An object representing the task definition for an Entities Recognition task.
EntitiesTaskParameters	Supported parameters for an Entity Recognition task.
EntityCategory	(Optional) request parameter that limits the output to the requested entity types included in this list. We will apply inclusionList before exclusionList
EntityLinkingLROTask	An object representing the task definition for an Entity Linking task.
EntityLinkingTaskParameters	Supported parameters for an Entity Linking task.
Error	The error object.
ErrorCode	Human-readable error code.
ErrorResponse	Error response.
ExtractiveSummarizationLROTask	An object representing the task definition for an Extractive Summarization task.
ExtractiveSummarizationSortingCriteria	The sorting criteria to use for the results of Extractive Summarization.
ExtractiveSummarizationTaskParameters	Supported parameters for an Extractive Summarization task.
fhirVersion	The FHIR Spec version that the result will use to format the fhirBundle. For additional information see https://www.hl7.org/fhir/overview.html.
healthcareDocumentType	Document type that can be provided as input for Fhir Documents. Expect to have fhirVersion provided when used. Behavior of using None enum is the same as not using the documentType parameter.
HealthcareLROTask
HealthcareTaskParameters	Supported parameters for a Healthcare task.
InnerErrorCode	Human-readable error code.
InnerErrorModel	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.
KeyPhraseLROTask	An object representing the task definition for a Key Phrase Extraction task.
KeyPhraseTaskParameters	Supported parameters for a Key Phrase Extraction task.
MatchLongestEntityPolicyType	Represents the Match longest overlap policy. No overlapping entities as far as it is possible. 1. If there are overlapping entities, the longest one will be returned. 2. If the set of characters predicted for 2 or more entities are exactly the same, select the entity that has the higher confidence score.3. If the entity scores are identical, return all entities that are still present after applying the previous rules. 3. If there is partial overlap (as in Hello Text Analytics) follow the above steps starting from 1.
MultiLanguageAnalysisInput
MultiLanguageInput	Contains an input document to be analyzed by the service.
PiiCategoriesExclude	(Optional) describes the PII categories to return
PiiCategory	(Optional) describes the PII categories to return
PiiDomain	The PII domain used for PII Entity Recognition.
PiiLROTask	An object representing the task definition for a PII Entities Recognition task.
PiiTaskParameters	Supported parameters for a PII Entities Recognition task.
redactionCharacter	Optional parameter to use a Custom Character to be used for redaction in PII responses. Default character will be * as before. We allow specific ascii characters for redaction.
SentimentAnalysisLROTask	An object representing the task definition for a Sentiment Analysis task.
SentimentAnalysisTaskParameters	Supported parameters for a Sentiment Analysis task.
StringIndexType	Specifies the method used to interpret string offsets. Defaults to Text Elements (Graphemes) according to Unicode v8.0.0. For additional information see https://aka.ms/text-analytics-offsets.

AbstractiveSummarizationLROTask

Object

An object representing the task definition for an Abstractive Summarization task.

Name	Type	Description
kind	string: AbstractiveSummarization	Enumeration of supported long-running Text Analysis tasks.
parameters	AbstractiveSummarizationTaskParameters	Supported parameters for the pre-build Abstractive Summarization task.
taskName	string

AbstractiveSummarizationTaskParameters

Object

Supported parameters for the pre-build Abstractive Summarization task.

Name	Type	Default value	Description
loggingOptOut	boolean	False
modelVersion	string	latest
sentenceCount	integer (int32)		It controls the approximate number of sentences in the output summaries.
stringIndexType	StringIndexType	TextElements_v8	Specifies the method used to interpret string offsets. Defaults to Text Elements (Graphemes) according to Unicode v8.0.0. For additional information see https://aka.ms/text-analytics-offsets.

AllowOverlapEntityPolicyType

Object

Represents the allow overlap policy. Will apply no post processing logic for the entities. Whatever the model predicts is what will be returned to the user. This allows the user to get a full view of every single model's possible values and apply their own custom logic on entity selection

Name	Type	Default value	Description
policyKind	string: allowOverlap	matchLongest	The entity OverlapPolicy object kind.

AnalyzeTextJobsInput

Object

Name	Type	Description
analysisInput	MultiLanguageAnalysisInput
defaultLanguage	string	Default language to use for records requesting automatic language detection.
displayName	string	Optional display name for the analysis job.
tasks	AnalyzeTextLROTask[]: AbstractiveSummarizationLROTask[] CustomAbstractiveSummarizationLROTask[] CustomEntitiesLROTask[] CustomHealthcareLROTask[] CustomMultiLabelClassificationLROTask[] CustomSentimentAnalysisLROTask[] CustomSingleLabelClassificationLROTask[] EntitiesLROTask[] EntityLinkingLROTask[] ExtractiveSummarizationLROTask[] HealthcareLROTask[] KeyPhraseLROTask[] PiiLROTask[] SentimentAnalysisLROTask[]	The set of tasks to execute on the input documents.

AnalyzeTextLROTaskKind

Enumeration

Enumeration of supported long-running Text Analysis tasks.

Value	Description
SentimentAnalysis
EntityRecognition
PiiEntityRecognition
KeyPhraseExtraction
EntityLinking
Healthcare
CustomHealthcare
ExtractiveSummarization
CustomEntityRecognition
CustomSingleLabelClassification
CustomMultiLabelClassification
AbstractiveSummarization
CustomSentimentAnalysis
CustomAbstractiveSummarization

CustomAbstractiveSummarizationLROTask

Object

An object representing the task definition for an Custom Abstractive Summarization task.

Name	Type	Description
kind	string: CustomAbstractiveSummarization	Enumeration of supported long-running Text Analysis tasks.
parameters	CustomAbstractiveSummarizationTaskParameters	Supported parameters for the Custom Abstractive Summarization task.
taskName	string

CustomAbstractiveSummarizationTaskParameters

Object

Supported parameters for the Custom Abstractive Summarization task.

Name	Type	Default value	Description
deploymentName	string		This field indicates the deployment name for the model.
loggingOptOut	boolean	False
projectName	string		This field indicates the project name for the model.
sentenceCount	integer (int32)		It controls the approximate number of sentences in the output summaries.
stringIndexType	StringIndexType	TextElements_v8	Specifies the method used to interpret string offsets. Defaults to Text Elements (Graphemes) according to Unicode v8.0.0. For additional information see https://aka.ms/text-analytics-offsets.

CustomEntitiesLROTask

Object

Use custom models to ease the process of information extraction from unstructured documents like contracts or financial documents

Name	Type	Description
kind	string: CustomEntityRecognition	Enumeration of supported long-running Text Analysis tasks.
parameters	CustomEntitiesTaskParameters	Supported parameters for a Custom Entities task.
taskName	string

CustomEntitiesTaskParameters

Object

Supported parameters for a Custom Entities task.

Name	Type	Default value	Description
deploymentName	string		This field indicates the deployment name for the model.
loggingOptOut	boolean	False
projectName	string		This field indicates the project name for the model.
stringIndexType	StringIndexType	TextElements_v8	Specifies the method used to interpret string offsets. Defaults to Text Elements (Graphemes) according to Unicode v8.0.0. For additional information see https://aka.ms/text-analytics-offsets.

CustomHealthcareLROTask

Object

Name	Type	Description
kind	string: CustomHealthcare	Enumeration of supported long-running Text Analysis tasks.
parameters	CustomHealthcareTaskParameters	Supported parameters for a custom Healthcare task.
taskName	string

CustomHealthcareTaskParameters

Object

Supported parameters for a custom Healthcare task.

Name	Type	Default value	Description
deploymentName	string		This field indicates the deployment name for the model.
loggingOptOut	boolean	False
projectName	string		This field indicates the project name for the model.
stringIndexType	StringIndexType	TextElements_v8	Specifies the method used to interpret string offsets. Defaults to Text Elements (Graphemes) according to Unicode v8.0.0. For additional information see https://aka.ms/text-analytics-offsets.

CustomMultiLabelClassificationLROTask

Object

Use custom models to classify text into multi label taxonomy

Name	Type	Description
kind	string: CustomMultiLabelClassification	Enumeration of supported long-running Text Analysis tasks.
parameters	CustomMultiLabelClassificationTaskParameters	Supported parameters for a Custom Multi Classification task.
taskName	string

CustomMultiLabelClassificationTaskParameters

Object

Supported parameters for a Custom Multi Classification task.

Name	Type	Default value	Description
deploymentName	string		This field indicates the deployment name for the model.
loggingOptOut	boolean	False
projectName	string		This field indicates the project name for the model.

CustomSentimentAnalysisLROTask

Object

Use custom models to ease the process of sentiment analysis from documents like product reviews

Name	Type	Description
kind	string: CustomSentimentAnalysis	Enumeration of supported long-running Text Analysis tasks.
parameters	CustomSentimentAnalysisTaskParameters	Supported parameters for a Custom Sentiment Analysis task.
taskName	string

CustomSentimentAnalysisTaskParameters

Object

Supported parameters for a Custom Sentiment Analysis task.

Name	Type	Default value	Description
deploymentName	string		This field indicates the deployment name for the model.
loggingOptOut	boolean	False
projectName	string		This field indicates the project name for the model.
stringIndexType	StringIndexType	TextElements_v8	Specifies the method used to interpret string offsets. Defaults to Text Elements (Graphemes) according to Unicode v8.0.0. For additional information see https://aka.ms/text-analytics-offsets.

CustomSingleLabelClassificationLROTask

Object

Use custom models to classify text into single label taxonomy

Name	Type	Description
kind	string: CustomSingleLabelClassification	Enumeration of supported long-running Text Analysis tasks.
parameters	CustomSingleLabelClassificationTaskParameters	Supported parameters for a Custom Single Classification task.
taskName	string

CustomSingleLabelClassificationTaskParameters

Object

Supported parameters for a Custom Single Classification task.

Name	Type	Default value	Description
deploymentName	string		This field indicates the deployment name for the model.
loggingOptOut	boolean	False
projectName	string		This field indicates the project name for the model.

EntitiesLROTask

Object

An object representing the task definition for an Entities Recognition task.

Name	Type	Description
kind	string: EntityRecognition	Enumeration of supported long-running Text Analysis tasks.
parameters	EntitiesTaskParameters	Supported parameters for an Entity Recognition task.
taskName	string

EntitiesTaskParameters

Object

Supported parameters for an Entity Recognition task.

Name	Type	Default value	Description
exclusionList	EntityCategory[]		(Optional) request parameter that filters out any entities that are included the excludeList. When a user specifies an excludeList, they cannot get a prediction returned with an entity in that list. We will apply inclusionList before exclusionList
inclusionList	EntityCategory[]		(Optional) request parameter that limits the output to the requested entity types included in this list. We will apply inclusionList before exclusionList
loggingOptOut	boolean	False
modelVersion	string	latest
overlapPolicy	BaseEntityOverlapPolicy: AllowOverlapEntityPolicyType MatchLongestEntityPolicyType		(Optional) describes the type of overlap policy to apply to the ner output.
stringIndexType	StringIndexType	TextElements_v8	Specifies the method used to interpret string offsets. Defaults to Text Elements (Graphemes) according to Unicode v8.0.0. For additional information see https://aka.ms/text-analytics-offsets.

EntityCategory

Enumeration

(Optional) request parameter that limits the output to the requested entity types included in this list. We will apply inclusionList before exclusionList

Value	Description
Address	Specific street-level mentions of locations: house/building numbers, streets, avenues, highways, intersections referenced by name.
Numeric	Numeric values, including digits and number words.
Age	Age-related values.
Currency	Currency-related values.
Number	Numbers without a unit
NumberRange	Range of Numbers
Percentage	Percentage-related values.
Ordinal	Ordinal numbers.
Temperature	Temperature-related values.
Dimension	Dimension of measurements
Length	Length of an object.
Weight	Weight of an object.
Height	Height of an object.
Speed	Speed of an object.
Area	Area of an object.
Volume	Volume of an object.
Information	Unit of measure for digital information.
Temporal	Items relating to time.
Date	Calendar dates.
Time	Times of day.
DateTime	Calendar dates with time.
DateRange	Range of dates.
TimeRange	Range of times.
DateTimeRange	Range of date and time.
Duration	Duration of time.
SetTemporal	Set of time-related values.
Event	Social, sports, business, political, educational, natural, historical, criminal, violent, legal, military events with a timed period.
SportsEvent	Sports event-related values.
CulturalEvent	Cultural event-related values.
NaturalEvent	Natural event-related values.
Location	Particular point or place in physical space.
GPE	Cities, countries/regions, states.
City	City-related values.
State	State-related values.
CountryRegion	Country or region-related values.
Continent	Continent-related values.
Structural	Manmade structures.
Airport	Airports.
Geological	Geographic and natural features such as rivers, oceans, and deserts.
Organization	Corporations, agencies, and other groups of people defined by some established organizational structure. These labels can include companies, political parties/movements, musical bands, sport clubs, government bodies, and public organizations. Nationalities or religions are not ORGANIZATION.
OrganizationMedical	Medical companies and groups.
OrganizationStockExchange	Stock exchange groups.
OrganizationSports	Sports-related organizations.
Person	First, last, and middle names, names of fictional characters, and aliases. Titles, such as “Mr.” or “President”, are not considered part of the named entity.
PersonType	Human roles classified by a group membership.
Email	Email addresses.
URL	URLs to websites.
IP	network IP addresses.
PhoneNumber	Phone numbers (US and EU phone numbers only).
Product	Single or group of commercial, consumable objects, electronics, vehicles, food groups.
ComputingProduct	Computing products.
Skill	A capability, skill, or expertise.

EntityLinkingLROTask

Object

An object representing the task definition for an Entity Linking task.

Name	Type	Description
kind	string: EntityLinking	Enumeration of supported long-running Text Analysis tasks.
parameters	EntityLinkingTaskParameters	Supported parameters for an Entity Linking task.
taskName	string

EntityLinkingTaskParameters

Object

Supported parameters for an Entity Linking task.

Name	Type	Default value	Description
loggingOptOut	boolean	False
modelVersion	string	latest
stringIndexType	StringIndexType	TextElements_v8	Specifies the method used to interpret string offsets. Defaults to Text Elements (Graphemes) according to Unicode v8.0.0. For additional information see https://aka.ms/text-analytics-offsets.

Error

Object

The error object.

Name	Type	Description
code	ErrorCode	One of a server-defined set of error codes.
details	Error[]	An array of details about specific errors that led to this reported error.
innererror	InnerErrorModel	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.

ErrorCode

Enumeration

Human-readable error code.

Value	Description
InvalidRequest
InvalidArgument
Unauthorized
Forbidden
NotFound
ProjectNotFound
OperationNotFound
AzureCognitiveSearchNotFound
AzureCognitiveSearchIndexNotFound
TooManyRequests
AzureCognitiveSearchThrottling
AzureCognitiveSearchIndexLimitReached
InternalServerError
ServiceUnavailable
Timeout
QuotaExceeded
Conflict
Warning

ErrorResponse

Object

Error response.

Name	Type	Description
error	Error	The error object.

ExtractiveSummarizationLROTask

Object

An object representing the task definition for an Extractive Summarization task.

Name	Type	Description
kind	string: ExtractiveSummarization	Enumeration of supported long-running Text Analysis tasks.
parameters	ExtractiveSummarizationTaskParameters	Supported parameters for an Extractive Summarization task.
taskName	string

ExtractiveSummarizationSortingCriteria

Enumeration

The sorting criteria to use for the results of Extractive Summarization.

Value	Description
Offset	Indicates that results should be sorted in order of appearance in the text.
Rank	Indicates that results should be sorted in order of importance (i.e. rank score) according to the model.

ExtractiveSummarizationTaskParameters

Object

Supported parameters for an Extractive Summarization task.

Name	Type	Default value	Description
loggingOptOut	boolean	False
modelVersion	string	latest
sentenceCount	integer (int64)	3
sortBy	ExtractiveSummarizationSortingCriteria	Offset	The sorting criteria to use for the results of Extractive Summarization.
stringIndexType	StringIndexType	TextElements_v8	Specifies the method used to interpret string offsets. Defaults to Text Elements (Graphemes) according to Unicode v8.0.0. For additional information see https://aka.ms/text-analytics-offsets.

fhirVersion

Enumeration

The FHIR Spec version that the result will use to format the fhirBundle. For additional information see https://www.hl7.org/fhir/overview.html.

Value	Description
4.0.1

healthcareDocumentType

Enumeration

Document type that can be provided as input for Fhir Documents. Expect to have fhirVersion provided when used. Behavior of using None enum is the same as not using the documentType parameter.

Value	Description
None
ClinicalTrial
DischargeSummary
ProgressNote
HistoryAndPhysical
Consult
Imaging
Pathology
ProcedureNote

HealthcareLROTask

Object

Name	Type	Description
kind	string: Healthcare	Enumeration of supported long-running Text Analysis tasks.
parameters	HealthcareTaskParameters	Supported parameters for a Healthcare task.
taskName	string

HealthcareTaskParameters

Object

Supported parameters for a Healthcare task.

Name	Type	Default value	Description
documentType	healthcareDocumentType		Document type that can be provided as input for Fhir Documents. Expect to have fhirVersion provided when used. Behavior of using None enum is the same as not using the documentType parameter.
fhirVersion	fhirVersion		The FHIR Spec version that the result will use to format the fhirBundle. For additional information see https://www.hl7.org/fhir/overview.html.
loggingOptOut	boolean	False
modelVersion	string	latest
stringIndexType	StringIndexType	TextElements_v8	Specifies the method used to interpret string offsets. Defaults to Text Elements (Graphemes) according to Unicode v8.0.0. For additional information see https://aka.ms/text-analytics-offsets.

InnerErrorCode

Enumeration

Human-readable error code.

Value	Description
InvalidRequest
InvalidParameterValue
KnowledgeBaseNotFound
AzureCognitiveSearchNotFound
AzureCognitiveSearchThrottling
ExtractionFailure
InvalidRequestBodyFormat
EmptyRequest
MissingInputDocuments
InvalidDocument
ModelVersionIncorrect
InvalidDocumentBatch
UnsupportedLanguageCode
InvalidCountryHint

InnerErrorModel

Object

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	InnerErrorCode	One of a server-defined set of error codes.
details	object	Error details.
innererror	InnerErrorModel	An object containing more specific information than the current object about the error.
message	string	Error message.
target	string	Error target.

KeyPhraseLROTask

Object

An object representing the task definition for a Key Phrase Extraction task.

Name	Type	Description
kind	string: KeyPhraseExtraction	Enumeration of supported long-running Text Analysis tasks.
parameters	KeyPhraseTaskParameters	Supported parameters for a Key Phrase Extraction task.
taskName	string

KeyPhraseTaskParameters

Object

Supported parameters for a Key Phrase Extraction task.

Name	Type	Default value	Description
loggingOptOut	boolean	False
modelVersion	string	latest

MatchLongestEntityPolicyType

Object

Represents the Match longest overlap policy. No overlapping entities as far as it is possible. 1. If there are overlapping entities, the longest one will be returned. 2. If the set of characters predicted for 2 or more entities are exactly the same, select the entity that has the higher confidence score.3. If the entity scores are identical, return all entities that are still present after applying the previous rules. 3. If there is partial overlap (as in Hello Text Analytics) follow the above steps starting from 1.

Name	Type	Default value	Description
policyKind	string: matchLongest	matchLongest	The entity OverlapPolicy object kind.

MultiLanguageAnalysisInput

Object

Name	Type	Description
documents	MultiLanguageInput[]	Contains an input document to be analyzed by the service.

MultiLanguageInput

Object

Contains an input document to be analyzed by the service.

Name	Type	Description
id	string	A unique, non-empty document identifier.
language	string	(Optional) This is the 2 letter ISO 639-1 representation of a language. For example, use "en" for English; "es" for Spanish etc. For Auto Language Detection, use "auto". If not set, use "en" for English as default.
text	string	The input text to process.

PiiCategoriesExclude

Enumeration

(Optional) describes the PII categories to return

Value	Description
ABARoutingNumber
ARNationalIdentityNumber
AUBankAccountNumber
AUDriversLicenseNumber
AUMedicalAccountNumber
AUPassportNumber
AUTaxFileNumber
AUBusinessNumber
AUCompanyNumber
ATIdentityCard
ATTaxIdentificationNumber
ATValueAddedTaxNumber
AzureDocumentDBAuthKey
AzureIAASDatabaseConnectionAndSQLString
AzureIoTConnectionString
AzurePublishSettingPassword
AzureRedisCacheString
AzureSAS
AzureServiceBusString
AzureStorageAccountKey
AzureStorageAccountGeneric
BENationalNumber
BENationalNumberV2
BEValueAddedTaxNumber
BRCPFNumber
BRLegalEntityNumber
BRNationalIDRG
BGUniformCivilNumber
CABankAccountNumber
CADriversLicenseNumber
CAHealthServiceNumber
CAPassportNumber
CAPersonalHealthIdentification
CASocialInsuranceNumber
CLIdentityCardNumber
CNResidentIdentityCardNumber
CreditCardNumber
HRIdentityCardNumber
HRNationalIDNumber
HRPersonalIdentificationNumber
HRPersonalIdentificationOIBNumberV2
CYIdentityCard
CYTaxIdentificationNumber
CZPersonalIdentityNumber
CZPersonalIdentityV2
DKPersonalIdentificationNumber
DKPersonalIdentificationV2
DrugEnforcementAgencyNumber
EEPersonalIdentificationCode
EUDebitCardNumber
EUDriversLicenseNumber
EUGPSCoordinates
EUNationalIdentificationNumber
EUPassportNumber
EUSocialSecurityNumber
EUTaxIdentificationNumber
FIEuropeanHealthNumber
FINationalID
FINationalIDV2
FIPassportNumber
FRDriversLicenseNumber
FRHealthInsuranceNumber
FRNationalID
FRPassportNumber
FRSocialSecurityNumber
FRTaxIdentificationNumber
FRValueAddedTaxNumber
DEDriversLicenseNumber
DEPassportNumber
DEIdentityCardNumber
DETaxIdentificationNumber
DEValueAddedNumber
GRNationalIDCard
GRNationalIDV2
GRTaxIdentificationNumber
HKIdentityCardNumber
HUValueAddedNumber
HUPersonalIdentificationNumber
HUTaxIdentificationNumber
INPermanentAccount
INUniqueIdentificationNumber
IDIdentityCardNumber
InternationalBankingAccountNumber
IEPersonalPublicServiceNumber
IEPersonalPublicServiceNumberV2
ILBankAccountNumber
ILNationalID
ITDriversLicenseNumber
ITFiscalCode
ITValueAddedTaxNumber
JPBankAccountNumber
JPDriversLicenseNumber
JPPassportNumber
JPResidentRegistrationNumber
JPSocialInsuranceNumber
JPMyNumberCorporate
JPMyNumberPersonal
JPResidenceCardNumber
LVPersonalCode
LTPersonalCode
LUNationalIdentificationNumberNatural
LUNationalIdentificationNumberNonNatural
MYIdentityCardNumber
MTIdentityCardNumber
MTTaxIDNumber
NLCitizensServiceNumber
NLCitizensServiceNumberV2
NLTaxIdentificationNumber
NLValueAddedTaxNumber
NZBankAccountNumber
NZDriversLicenseNumber
NZInlandRevenueNumber
NZMinistryOfHealthNumber
NZSocialWelfareNumber
NOIdentityNumber
PHUnifiedMultiPurposeIDNumber
PLIdentityCard
PLNationalID
PLNationalIDV2
PLPassportNumber
PLTaxIdentificationNumber
PLREGONNumber
PTCitizenCardNumber
PTCitizenCardNumberV2
PTTaxIdentificationNumber
ROPersonalNumericalCode
RUPassportNumberDomestic
RUPassportNumberInternational
SANationalID
SGNationalRegistrationIdentityCardNumber
SKPersonalNumber
SITaxIdentificationNumber
SIUniqueMasterCitizenNumber
ZAIdentificationNumber
KRResidentRegistrationNumber
ESDNI
ESSocialSecurityNumber
ESTaxIdentificationNumber
SQLServerConnectionString
SENationalID
SENationalIDV2
SEPassportNumber
SETaxIdentificationNumber
SWIFTCode
CHSocialSecurityNumber
TWNationalID
TWPassportNumber
TWResidentCertificate
THPopulationIdentificationCode
TRNationalIdentificationNumber
UKDriversLicenseNumber
UKElectoralRollNumber
UKNationalHealthNumber
UKNationalInsuranceNumber
UKUniqueTaxpayerNumber
USUKPassportNumber
USBankAccountNumber
USDriversLicenseNumber
USIndividualTaxpayerIdentification
USSocialSecurityNumber
UAPassportNumberDomestic
UAPassportNumberInternational
Organization
Email
URL
Age
PhoneNumber
IPAddress
Date
Person
Address

PiiCategory

Enumeration

(Optional) describes the PII categories to return

Value	Description
ABARoutingNumber
ARNationalIdentityNumber
AUBankAccountNumber
AUDriversLicenseNumber
AUMedicalAccountNumber
AUPassportNumber
AUTaxFileNumber
AUBusinessNumber
AUCompanyNumber
ATIdentityCard
ATTaxIdentificationNumber
ATValueAddedTaxNumber
AzureDocumentDBAuthKey
AzureIAASDatabaseConnectionAndSQLString
AzureIoTConnectionString
AzurePublishSettingPassword
AzureRedisCacheString
AzureSAS
AzureServiceBusString
AzureStorageAccountKey
AzureStorageAccountGeneric
BENationalNumber
BENationalNumberV2
BEValueAddedTaxNumber
BRCPFNumber
BRLegalEntityNumber
BRNationalIDRG
BGUniformCivilNumber
CABankAccountNumber
CADriversLicenseNumber
CAHealthServiceNumber
CAPassportNumber
CAPersonalHealthIdentification
CASocialInsuranceNumber
CLIdentityCardNumber
CNResidentIdentityCardNumber
CreditCardNumber
HRIdentityCardNumber
HRNationalIDNumber
HRPersonalIdentificationNumber
HRPersonalIdentificationOIBNumberV2
CYIdentityCard
CYTaxIdentificationNumber
CZPersonalIdentityNumber
CZPersonalIdentityV2
DKPersonalIdentificationNumber
DKPersonalIdentificationV2
DrugEnforcementAgencyNumber
EEPersonalIdentificationCode
EUDebitCardNumber
EUDriversLicenseNumber
EUGPSCoordinates
EUNationalIdentificationNumber
EUPassportNumber
EUSocialSecurityNumber
EUTaxIdentificationNumber
FIEuropeanHealthNumber
FINationalID
FINationalIDV2
FIPassportNumber
FRDriversLicenseNumber
FRHealthInsuranceNumber
FRNationalID
FRPassportNumber
FRSocialSecurityNumber
FRTaxIdentificationNumber
FRValueAddedTaxNumber
DEDriversLicenseNumber
DEPassportNumber
DEIdentityCardNumber
DETaxIdentificationNumber
DEValueAddedNumber
GRNationalIDCard
GRNationalIDV2
GRTaxIdentificationNumber
HKIdentityCardNumber
HUValueAddedNumber
HUPersonalIdentificationNumber
HUTaxIdentificationNumber
INPermanentAccount
INUniqueIdentificationNumber
IDIdentityCardNumber
InternationalBankingAccountNumber
IEPersonalPublicServiceNumber
IEPersonalPublicServiceNumberV2
ILBankAccountNumber
ILNationalID
ITDriversLicenseNumber
ITFiscalCode
ITValueAddedTaxNumber
JPBankAccountNumber
JPDriversLicenseNumber
JPPassportNumber
JPResidentRegistrationNumber
JPSocialInsuranceNumber
JPMyNumberCorporate
JPMyNumberPersonal
JPResidenceCardNumber
LVPersonalCode
LTPersonalCode
LUNationalIdentificationNumberNatural
LUNationalIdentificationNumberNonNatural
MYIdentityCardNumber
MTIdentityCardNumber
MTTaxIDNumber
NLCitizensServiceNumber
NLCitizensServiceNumberV2
NLTaxIdentificationNumber
NLValueAddedTaxNumber
NZBankAccountNumber
NZDriversLicenseNumber
NZInlandRevenueNumber
NZMinistryOfHealthNumber
NZSocialWelfareNumber
NOIdentityNumber
PHUnifiedMultiPurposeIDNumber
PLIdentityCard
PLNationalID
PLNationalIDV2
PLPassportNumber
PLTaxIdentificationNumber
PLREGONNumber
PTCitizenCardNumber
PTCitizenCardNumberV2
PTTaxIdentificationNumber
ROPersonalNumericalCode
RUPassportNumberDomestic
RUPassportNumberInternational
SANationalID
SGNationalRegistrationIdentityCardNumber
SKPersonalNumber
SITaxIdentificationNumber
SIUniqueMasterCitizenNumber
ZAIdentificationNumber
KRResidentRegistrationNumber
ESDNI
ESSocialSecurityNumber
ESTaxIdentificationNumber
SQLServerConnectionString
SENationalID
SENationalIDV2
SEPassportNumber
SETaxIdentificationNumber
SWIFTCode
CHSocialSecurityNumber
TWNationalID
TWPassportNumber
TWResidentCertificate
THPopulationIdentificationCode
TRNationalIdentificationNumber
UKDriversLicenseNumber
UKElectoralRollNumber
UKNationalHealthNumber
UKNationalInsuranceNumber
UKUniqueTaxpayerNumber
USUKPassportNumber
USBankAccountNumber
USDriversLicenseNumber
USIndividualTaxpayerIdentification
USSocialSecurityNumber
UAPassportNumberDomestic
UAPassportNumberInternational
Organization
Email
URL
Age
PhoneNumber
IPAddress
Date
Person
Address
All
Default

PiiDomain

Enumeration

The PII domain used for PII Entity Recognition.

Value	Description
phi	Indicates that entities in the Personal Health Information domain should be redacted.
none	Indicates that no domain is specified.

PiiLROTask

Object

An object representing the task definition for a PII Entities Recognition task.

Name	Type	Description
kind	string: PiiEntityRecognition	Enumeration of supported long-running Text Analysis tasks.
parameters	PiiTaskParameters	Supported parameters for a PII Entities Recognition task.
taskName	string

PiiTaskParameters

Object

Supported parameters for a PII Entities Recognition task.

Name	Type	Default value	Description
domain	PiiDomain	none	The PII domain used for PII Entity Recognition.
excludePiiCategories	PiiCategoriesExclude[]		(Optional) describes the PII categories to return
loggingOptOut	boolean	False
modelVersion	string	latest
piiCategories	PiiCategory[]		(Optional) describes the PII categories to return
redactionCharacter	redactionCharacter	*	Optional parameter to use a Custom Character to be used for redaction in PII responses. Default character will be * as before. We allow specific ascii characters for redaction.
stringIndexType	StringIndexType	TextElements_v8	Specifies the method used to interpret string offsets. Defaults to Text Elements (Graphemes) according to Unicode v8.0.0. For additional information see https://aka.ms/text-analytics-offsets.

redactionCharacter

Enumeration

Optional parameter to use a Custom Character to be used for redaction in PII responses. Default character will be * as before. We allow specific ascii characters for redaction.

Value	Description
!
#
$
%
&
*
+
-
=
?
@
^
_
~

SentimentAnalysisLROTask

Object

An object representing the task definition for a Sentiment Analysis task.

Name	Type	Description
kind	string: SentimentAnalysis	Enumeration of supported long-running Text Analysis tasks.
parameters	SentimentAnalysisTaskParameters	Supported parameters for a Sentiment Analysis task.
taskName	string

SentimentAnalysisTaskParameters

Object

Supported parameters for a Sentiment Analysis task.

Name	Type	Default value	Description
loggingOptOut	boolean	False
modelVersion	string	latest
opinionMining	boolean	False
stringIndexType	StringIndexType	TextElements_v8	Specifies the method used to interpret string offsets. Defaults to Text Elements (Graphemes) according to Unicode v8.0.0. For additional information see https://aka.ms/text-analytics-offsets.

StringIndexType

Enumeration

Specifies the method used to interpret string offsets. Defaults to Text Elements (Graphemes) according to Unicode v8.0.0. For additional information see https://aka.ms/text-analytics-offsets.

Value	Description
TextElements_v8	Returned offset and length values will correspond to TextElements (Graphemes and Grapheme clusters) confirming to the Unicode 8.0.0 standard. Use this option if your application is written in .Net Framework or .Net Core and you will be using StringInfo.
UnicodeCodePoint	Returned offset and length values will correspond to Unicode code points. Use this option if your application is written in a language that support Unicode, for example Python.
Utf16CodeUnit	Returned offset and length values will correspond to UTF-16 code units. Use this option if your application is written in a language that support Unicode, for example Java, JavaScript.

Share via

Analyze Text - Submit Job

URI Parameters

Request Body

Responses

Security

AADToken

Notes

Scopes

Ocp-Apim-Subscription-Key

Examples

Successful Custom Healthcare Post Request

Sample request

Sample response

Successful Custom Sentiment Analysis Post Request

Sample request

Sample response

Successful Healthcare DocumentType Post Request

Sample request

Sample response

Successful Healthcare Post Request

Sample request

Sample response

Successful Submit Abstractive Summarization Task

Sample request

Sample response

Successful Submit Analysis Job Request

Sample request

Sample response

Successful Submit Custom Abstractive Summarization Task

Sample request

Sample response

Definitions

AbstractiveSummarizationLROTask

AbstractiveSummarizationTaskParameters

AllowOverlapEntityPolicyType

AnalyzeTextJobsInput

AnalyzeTextLROTaskKind

CustomAbstractiveSummarizationLROTask

CustomAbstractiveSummarizationTaskParameters

CustomEntitiesLROTask

CustomEntitiesTaskParameters

CustomHealthcareLROTask

CustomHealthcareTaskParameters

CustomMultiLabelClassificationLROTask

CustomMultiLabelClassificationTaskParameters

CustomSentimentAnalysisLROTask

CustomSentimentAnalysisTaskParameters

CustomSingleLabelClassificationLROTask

CustomSingleLabelClassificationTaskParameters

EntitiesLROTask

EntitiesTaskParameters

EntityCategory

EntityLinkingLROTask

EntityLinkingTaskParameters

Error

ErrorCode

ErrorResponse

ExtractiveSummarizationLROTask

ExtractiveSummarizationSortingCriteria

ExtractiveSummarizationTaskParameters

fhirVersion

healthcareDocumentType

HealthcareLROTask

HealthcareTaskParameters

InnerErrorCode

InnerErrorModel

KeyPhraseLROTask

KeyPhraseTaskParameters

MatchLongestEntityPolicyType

MultiLanguageAnalysisInput

MultiLanguageInput

PiiCategoriesExclude

PiiCategory

PiiDomain

PiiLROTask

PiiTaskParameters

redactionCharacter

SentimentAnalysisLROTask

SentimentAnalysisTaskParameters