Document Models - Analyze Document

Service:

Azure AI Services

API Version:

2023-07-31

Analyzes document with document model.

POST {endpoint}/formrecognizer/documentModels/{modelId}:analyze?api-version=2023-07-31

With optional parameters:

POST {endpoint}/formrecognizer/documentModels/{modelId}:analyze?pages={pages}&locale={locale}&stringIndexType={stringIndexType}&api-version=2023-07-31&features={features}

URI Parameters

Name	In	Required	Type	Description
endpoint	path	True	string url	Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus2.api.cognitive.microsoft.com).
modelId	path	True	string	Unique document model name. Regex pattern: ^[a-zA-Z0-9][a-zA-Z0-9._~-]{1,63}$
api-version	query	True	string	Requested API version.
features	query		DocumentAnalysisFeature[]	List of optional analysis features.
locale	query		string	Locale hint for text recognition and document analysis. Value may contain only the language code (ex. "en", "fr") or BCP 47 language tag (ex. "en-US").
pages	query		string	List of 1-based page numbers to analyze. Ex. "1-3,5,7-9" Regex pattern: ^(\d+(-\d+)?)(,\s*(\d+(-\d+)?))*$
stringIndexType	query		StringIndexType	Method used to compute string offset and length.

Request Header

Media Types: "application/json", "application/octet-stream", "application/pdf", "image/jpeg", "image/png", "image/tiff", "image/bmp", "image/heif", "text/html", "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "application/vnd.openxmlformats-officedocument.presentationml.presentation"

Name	Required	Type	Description
Ocp-Apim-Subscription-Key	True	string	The secret key for your Azure Cognitive Services subscription.

Request Body

Media Types: "application/json", "application/octet-stream", "application/pdf", "image/jpeg", "image/png", "image/tiff", "image/bmp", "image/heif", "text/html", "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "application/vnd.openxmlformats-officedocument.presentationml.presentation"

Name	Type	Description
base64Source	string	Base64 encoding of the document to analyze. Either urlSource or base64Source must be specified.
urlSource	string	Document URL to analyze. Either urlSource or base64Source must be specified.

Responses

Name	Type	Description
202 Accepted		Request is queued successfully. Headers Operation-Location: string
Other Status Codes	ErrorResponse	Error encountered.

Security

Ocp-Apim-Subscription-Key

The secret key for your Azure Cognitive Services subscription.

Type: apiKey
In: header

Examples

Analyze Document from Base64

Analyze Document from Url

Analyze Document from Base64

Sample Request

HTTP

POST https://myendpoint.cognitiveservices.azure.com/formrecognizer/documentModels/prebuilt-layout:analyze?pages=1-2,4&locale=en-US&stringIndexType=textElements&api-version=2023-07-31

{
  "base64Source": "e2Jhc2U2NEVuY29kZWRQZGZ9"
}

Sample Response

Status code:

202

Operation-Location: https://myendpoint.cognitiveservices.azure.com/formrecognizer/documentModels/prebuilt-layout/analyzeResults/3b31320d-8bab-4f88-b19c-2322a7f11034?api-version=2023-07-31

Analyze Document from Url

Sample Request

HTTP

POST https://myendpoint.cognitiveservices.azure.com/formrecognizer/documentModels/customModel:analyze?pages=1-2,4&locale=en-US&stringIndexType=textElements&api-version=2023-07-31

{
  "urlSource": "http://host.com/doc.pdf"
}

Sample Response

Status code:

202

Operation-Location: https://myendpoint.cognitiveservices.azure.com/formrecognizer/documentModels/customModel/analyzeResults/3b31320d-8bab-4f88-b19c-2322a7f11034?api-version=2023-07-31

Definitions

Name	Description
AnalyzeDocumentRequest	Document analysis parameters.
DocumentAnalysisFeature	List of optional analysis features.
Error	Error info.
ErrorResponse	Error response object.
InnerError	Detailed error.
StringIndexType	Method used to compute string offset and length.

AnalyzeDocumentRequest

Document analysis parameters.

Name	Type	Description
base64Source	string	Base64 encoding of the document to analyze. Either urlSource or base64Source must be specified.
urlSource	string	Document URL to analyze. Either urlSource or base64Source must be specified.

DocumentAnalysisFeature

List of optional analysis features.

Name	Type	Description
barcodes	string	Enable the detection of barcodes in the document.
formulas	string	Enable the detection of mathematical expressions in the document.
keyValuePairs	string	Enable the detection of general key value pairs (form fields) in the document.
languages	string	Enable the detection of the text content language.
ocrHighResolution	string	Perform OCR at a higher resolution to handle documents with fine print.
styleFont	string	Enable the recognition of various font styles.

Error

Error info.

Name	Type	Description
code	string	Error code.
details	Error[]	List of detailed errors.
innererror	InnerError	Detailed error.
message	string	Error message.
target	string	Target of the error.

ErrorResponse

Error response object.

Name	Type	Description
error	Error	Error info.

InnerError

Detailed error.

Name	Type	Description
code	string	Error code.
innererror	InnerError	Detailed error.
message	string	Error message.

StringIndexType

Method used to compute string offset and length.

Name	Type	Description
textElements	string	User-perceived display character, or grapheme cluster, as defined by Unicode 8.0.0.
unicodeCodePoint	string	Character unit represented by a single unicode code point. Used by Python 3.
utf16CodeUnit	string	Character unit represented by a 16-bit Unicode code unit. Used by JavaScript, Java, and .NET.