Guide to Azure AI Document Intelligence covering REST and SDK calls, polling for results, interpreting structured OCR outputs, and testing prebuilt document models in Document Intelligence Studio.
Working with Azure AI Document Intelligence — practical guidance for calling the API, handling results, and using prebuilt models in the portal.This article shows the common request pattern (REST and SDK), how to poll and retrieve results, what the structured response contains, and how to test prebuilt models in Document Intelligence Studio.How the API call pattern works
Set up the request — define your resource endpoint and include the API key to authenticate.
Send the request — the service accepts the request and returns a poller/tracker. For REST this is the Operation-Location response header; SDKs handle polling internally.
Retrieve results — poll the Operation-Location URL until the operation completes (REST) or call the SDK’s wait/complete mechanism to get the final results.
When using the REST API you must explicitly poll the Operation-Location URL to receive results. SDKs abstract the polling and return a language-native result object when processing completes.
REST call pattern example
Below is a minimal REST POST to the prebuilt layout analyze endpoint. Note the Operation-Location header returned after submission — you poll that URL to check the status and fetch results.
Copy
POST {endpoint}/documentintelligence/documentModels/prebuilt-layout:analyze?api-version={version}Ocp-Apim-Subscription-Key: {key}Content-Type: application/json{ "urlSource": "{document_url}"}
The api-version parameter in the request and operation URL selects which API behavior/version you want to use when Microsoft introduces changes.SDK usage (C# and Python)
C# (Azure SDK): call AnalyzeDocumentFromUriAsync, wait for completion, then read Operation.Value for the AnalyzeResult.
Copy
AnalyzeDocumentOperation operation = await client.AnalyzeDocumentFromUriAsync( WaitUntil.Completed, "prebuilt-layout", fileUri);AnalyzeResult result = operation.Value;// result contains extracted contents such as text, tables, and layout information
Python (Azure SDK): start the analysis with a begin_* method and call poller.result() to obtain the structured result object.
Copy
poller = document_analysis_client.begin_analyze_document_from_url( "prebuilt-document", doc_url)result = poller.result()# 'result' now contains structured output: pages, lines, words, tables, fields, etc.
Response structure and metadata
The service returns a structured hierarchy that makes it easy to navigate OCR output:Pages → Lines → WordsThis structure lets you extract entire paragraphs, iterate line-by-line, or work with word-level details (content, bounding boxes, confidence, etc.).
A simplified REST JSON snippet (analyzeResult) showing modelId, pages, and word-level data:
The response contains rich metadata — bounding box coordinates, confidence scores, detected text style (including handwriting) — which you can use to validate fields, overlay extracted text on images, or apply post-processing rules.
Deploying Document Intelligence in Azure and trying prebuilt models
You can create either an AI multi-service (Cognitive Services) resource or a dedicated Document Intelligence resource in the Azure portal. After provisioning, open Document Intelligence Studio to test prebuilt models: invoices, receipts, IDs, health insurance cards, bank statements, and more.
To use a prebuilt model in the Studio, configure the API endpoint and a key for your service and then run sample documents through the UI.
Try sample identity documents (passport, driver’s license, green card, etc.) and inspect extracted fields such as name, date of birth, document number, and expiration.
Python SDK example — analyze an identity document from a URL
This consolidated Python example uses the Document Intelligence SDK to analyze an identity document at a given URL and iterate over extracted fields.
Copy
from azure.core.credentials import AzureKeyCredentialfrom azure.ai.documentintelligence import DocumentIntelligenceClientDOCUMENT_URL = "https://azai102imagestore.blob.core.windows.net/us-id-cards/id1.jpeg"DOC_INTEL_ENDPOINT = "https://aiservicesai900.cognitiveservices.azure.com/"DOC_INTEL_KEY = "2nDOsJoeWNZsci1GmRVpC88rpvMsF3wF5KjGqcrSUqmjAXIN6zrLJQQJ99AKACYeBjFXJ3w3AAAAACOGR0oi"client = DocumentIntelligenceClient( endpoint=DOC_INTEL_ENDPOINT, credential=AzureKeyCredential(DOC_INTEL_KEY))poller = client.begin_analyze_document( model_id="prebuilt-idDocument", body={"urlSource": DOCUMENT_URL})result = poller.result()for i, doc in enumerate(result.documents, start=1): print(f"\n— Document #{i} (type: {doc.doc_type}) -----------------------------") for name, field in doc.fields.items(): value = field.content if field.content is not None else "<no value>" print(f"{name:20s}: {str(value):30s} (confidence: {field.confidence:.2f})")
Handling download errors
If the service cannot download the document from the supplied URL (for example, wrong filename or access issues) you may receive an HttpResponseError similar to this:
Copy
azure.core.exceptions.HttpResponseError: (InvalidRequest) Invalid request.Code: InvalidRequestMessage: Invalid request.Inner error: { "code": "InvalidContent", "message": "Could not download the file from the given URL."}
Common causes: incorrect blob name/extension, broken URL, or container not publicly accessible. Ensure the URL is reachable and points to the correct file before re-running the analysis.
Example: wrong extension (id2.jpeg vs id2.jpg) prevented download — after fixing the blob name and re-running the same code against id2.jpg the expected extraction was returned:
That demonstrates how to work with Document Intelligence: configure access, call the analyze endpoint (REST or SDK), poll (if REST), and consume the structured output (pages → lines → words and high-level fields).
