Azure Document Intelligence: Setup, Models, and SDK Guide

Azure Document Intelligence is Microsoft's managed API for extracting structured data from documents. It goes beyond basic OCR by understanding document structure: field relationships, table geometry, key-value pairs, and document type. The current generally available release is v4.0 (API version 2024-11-30), which shipped November 2024.

Two facts frame any evaluation. This is a developer-facing API, not a turnkey product: a production pipeline typically requires 40 to 80 engineering hours to provision, integrate, and build surrounding UI, per Parsli's February 2026 analysis. The service also sits inside the Azure compliance perimeter, inheriting SOC 1/2/3, ISO 27001, HIPAA, PCI DSS, and FedRAMP certifications, which matters for regulated industries.

Prerequisites

Before writing any code, you need:

• An Azure subscription with permission to create resources
• A Document Intelligence resource provisioned in the Azure portal (choose a region; regional endpoints do not support Microsoft Entra token authentication; a custom subdomain is required for that)
• Your endpoint URL and either an API key or a managed identity configured
• The SDK for your language: azure-ai-documentintelligence on PyPI, NuGet, Maven, or npm

The free tier (F0) provides 500 pages per month, capped at 2 pages per request, with a 4 MB file size limit and 1 transaction per second. It covers all features but is not suitable for production workloads.

Model tiers

Document Intelligence organizes capabilities into three tiers. Choosing the right one before building saves significant rework.

Read is the foundational OCR layer. It extracts printed and handwritten text from PDFs, scanned images, and Office formats (DOCX, XLSX, PPTX, HTML), returning words, lines, paragraphs, bounding polygon coordinates, and confidence scores. It also produces searchable PDF output at no additional charge. Supported image formats: JPEG, PNG, BMP, TIFF, HEIF. PDF and TIFF processing supports up to 2,000 pages per document. Minimum readable text height is 12 pixels on a 1024x768 image, roughly 8-point text at 150 DPI.

Layout adds structural understanding on top of OCR: tables, selection marks, titles, section headings, and document hierarchy, without any training. Output is JSON. As of v4.0, Layout supports figure detection with figures downloadable as image files, and improved OCR for single characters, boxed text, and dense text.

Prebuilt models handle specific document types without training. The current catalog covers approximately 14 document types: Invoice, Receipt, ID Document, Business Card, W-2, 1098, 1099 variants, 1095A/C, Health Insurance Card, Contract, Credit Card, Pay Stub, Check, and US Mortgage forms. Tax form models were updated in March 2026 to support 2025 tax forms, including improved multi-copy extraction for documents containing multiple W-2s or 1099s. The Mortgage prebuilt supports signature detection on forms 1003, 1004, 1005, and closing disclosure.

Custom models cover document types not in the prebuilt catalog. Three training approaches are available:

• Template models: fixed-layout forms, minimum 5 labeled examples, capped at 500 training pages
• Neural models: variable-layout documents, up to 50,000 training pages, highest accuracy for English with marginal accuracy drop for other Latin-script languages
• Composite models: combine multiple custom models and automatically classify incoming documents, returning a docType property identifying which sub-model processed each document

Custom neural models now support signature detection and incremental training, so new document classes can be added to an existing classifier without full retraining.

Authentication and SDK setup

Two authentication methods are supported across all four language SDKs (Python, C#/.NET, Java, JavaScript):

## API key authentication
from azure.core.credentials import AzureKeyCredential
from azure.ai.documentintelligence import DocumentIntelligenceClient

client = DocumentIntelligenceClient(
    endpoint="https://<your-resource>.cognitiveservices.azure.com/",
    credential=AzureKeyCredential("<your-api-key>")
)

## Microsoft Entra ID (managed identity): requires custom subdomain endpoint
from azure.identity import DefaultAzureCredential
from azure.ai.documentintelligence import DocumentIntelligenceClient

client = DocumentIntelligenceClient(
    endpoint="https://<your-custom-subdomain>.cognitiveservices.azure.com/",
    credential=DefaultAzureCredential()
)

Regional endpoints (e.g., eastus.api.cognitive.microsoft.com) do not support Entra authentication. Provision a custom subdomain in the Azure portal if your organization disables key-based authentication.

Calling the API: sync vs. async

Synchronous calls return immediately but are limited to single-page documents. For multipage PDFs, use the async API and poll for completion.

## Async pattern for multipage documents
import time

poller = client.begin_analyze_document(
    model_id="prebuilt-invoice",
    analyze_request={"urlSource": "https://example.com/invoice.pdf"}
)
result = poller.result()  # SDK handles polling internally

for document in result.documents:
    for field_name, field in document.fields.items():
        print(f"{field_name}: {field.content} (confidence: {field.confidence})")

Expected output for an invoice includes fields like VendorName, InvoiceTotal, DueDate, and line items under Items, each with a confidence score between 0 and 1. Scores below 0.7 on critical fields typically warrant human review.

The v4.0 Batch API now supports all model types, including Read, Layout, prebuilt, and custom models, with LIST and DELETE functions for batch job management.

Document Intelligence Studio

Document Intelligence Studio provides a visual interface for testing prebuilt models, labeling training data, and evaluating extraction quality without writing code. It has supported Microsoft Entra authentication since May 2024. Use it to validate model selection before committing to SDK integration: uploading a sample document takes under two minutes and shows field-level confidence scores immediately.

For custom model development, the Studio's label-and-train interface does not require machine learning expertise. Neural model training is free for the first 10 hours per subscription per region per month, then $3 per hour.

Pricing

Pricing uses a per-page model. The figures below combine the official Azure pricing page and Parsli's February 2026 analysis. Where they differ, both are shown: verify current rates directly before budgeting.

The discrepancy likely reflects which endpoint tier is being quoted. Parsli's total cost analysis found teams typically spend 25 to 35% above the listed API rate once Azure Blob Storage for document staging, Logic Apps for orchestration, and developer integration time are included.

Commitment-based pricing is available for high-volume custom extraction: $400/month for 20,000 pages, $1,500/month for 100,000 pages, $6,000/month for 500,000 pages. Disconnected container pricing is available on an annual commitment basis for air-gapped deployments.

API version lifecycle

One breaking change when migrating from v3.0 to v3.1 or later: the boundingBox property in analyze response JSON was renamed to polygon. The v3.1 API also consolidated layout, prebuilt, and custom model analysis into a single operation pair using documentModels and modelId parameters. The v3.1 migration guide covers all breaking changes.

Common failure modes

Auth errors on regional endpoints. If you receive a 401 using Entra credentials, you are likely hitting a regional endpoint. Switch to a custom subdomain.

File size and page limits. The free tier caps files at 4 MB and 2 pages per request. The paid tier supports up to 500 MB and 2,000 pages for PDF/TIFF. Submitting an oversized file returns a 400 error with a clear message.

Low confidence on handwritten text. Document Intelligence benchmarks at 78.2% handwriting accuracy per Jannik Reinhard's February 2026 comparative analysis. For handwriting-heavy documents, set a confidence threshold and route low-confidence results to human review.

Polling timeouts on large batches. The SDK's poller.result() has a default timeout. For large documents, pass an explicit timeout parameter or implement your own polling loop against the operation URL.

Training data quality for custom models. Neural models require a minimum of 5 labeled documents; accuracy improves significantly up to around 50. Poorly labeled training data is the most common cause of low extraction accuracy on custom models.

RAG pipeline integration

For RAG pipelines, the Layout model's JSON output provides document structure that pure OCR services cannot. As Anurag Chatterjee noted in a December 2025 technical guide on Medium: "In my experience an OCR service alone falls short of what is typically expected in RAG use cases where the chunked content should have a coherent meaning."

The Layout model's output maps headings, tables, and figures to their positions in the document, enabling semantically coherent chunking before embedding. A hybrid approach combining the Read or Layout model for fast structured extraction with a vision-language model (VLM) for downstream reasoning can outperform either service alone on complex question-answering tasks. VLMs process 16 to 33 seconds per page versus Document Intelligence's 2 to 4 seconds, so for high-throughput pipelines the speed difference is a practical constraint (Jannik Reinhard, February 2026).

What practitioners report

Teams in Microsoft-heavy environments report that Document Intelligence integrates with Azure AI Search, Power Automate, and Azure OpenAI without additional configuration, which reduces pipeline build time significantly. As ocrvendors.com noted in their 2026 review: "If your company is a Microsoft shop, this is the obvious pick."

The friction points practitioners cite most often: the service lacks built-in intake and output integrations (email forwarding, drag-and-drop upload, routing to tools like Sheets or QuickBooks), which must be built separately via Logic Apps or custom code. Teams outside the Microsoft ecosystem also flag vendor lock-in as a documented limitation, since the API surface and authentication model assume Azure infrastructure throughout.

When to use something else

Document Intelligence is the right choice when your document types have a prebuilt model, your deployment environment requires on-premises containers, or your surrounding workflow is already built on Azure services.

Consider alternatives in these cases:

Azure Content Understanding (GA November 2025) is Microsoft's own multimodal successor. It supports derived field generation, multi-file input validation in a single request, and a Pro mode with reasoning and external knowledge base integration. For complex workflows that go beyond structured extraction, it may be the better fit for Azure-native teams.

Mistral OCR 3 (December 2025) claims 96.6% table extraction accuracy at $2 per 1,000 pages standard or $1 per 1,000 pages for batch. Reinhard's analysis notes these benchmarks are vendor-internal: "Independent comparisons using identical test sets are still lacking. Running your own tests with your document types is essential."

AWS Textract covers invoices, IDs, and lending documents but is cloud-only with no container deployment option. Document Intelligence's broader prebuilt catalog and on-premises container support give it an edge for regulated industries with data residency requirements.

Rossum and Nanonets offer turnkey products with built-in intake, review UI, and output routing, reducing the 40 to 80 engineering hours that a Document Intelligence pipeline typically requires. If your team lacks Azure infrastructure expertise, a managed IDP product may reach production faster.

For a broader comparison of IDP guides and extraction approaches, the idp-software.com guide library covers OCR engines, LLM extraction, and pipeline patterns across the full vendor landscape.