Document Intelligence: Read, Layout and Prebuilt Models

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production.

See the section bibliography for the reference material consulted while preparing these pages.

This page targets Azure CLI 2.90.0, the Document Intelligence REST API v4.0 2024-11-30, and the client libraries azure-ai-documentintelligence 1.0.2 (Python), Azure.AI.DocumentIntelligence 1.0.0 (.NET), com.azure:azure-ai-documentintelligence 1.0.10 (Java) and @azure-rest/ai-document-intelligence 1.1.0 (JavaScript), checked on 2026-10-06. The Learn C# quickstart still shows beta-era type names; the examples here use the GA 1.0.0 types.

Azure Document Intelligence in Foundry Tools (formerly Form Recognizer) extracts text, structure and fields from documents: scanned PDFs, photos, Office files and HTML. It gives deterministic output with page coordinates and a confidence score for every field.

Older API versions have end-of-support dates: v2.1 on 2027-09-15 and v3.0 on 2029-03-30. Move to v4.0 2024-11-30 and the azure-ai-documentintelligence libraries (the old azure-ai-formrecognizer package targets v3.x).

The v4.0 model catalog

Model ID Extracts

prebuilt-read

Text lines, words, languages and handwriting, from every supported format. Microsoft’s recommended OCR.

prebuilt-layout

Read plus tables, selection marks, paragraphs with roles (title, section heading, page header), sections and figures. Can output Markdown.

prebuilt-invoice, prebuilt-receipt

Vendor, customer, line items, totals and taxes; merchant, items and totals.

prebuilt-idDocument

Passports, driver’s licenses and ID cards from many countries.

prebuilt-contract, prebuilt-bankStatement.us, prebuilt-healthInsuranceCard.us, prebuilt-check.us, prebuilt-payStub.us, prebuilt-marriageCertificate.us, prebuilt-creditCard

Domain fields for each document type.

prebuilt-tax.us.* and prebuilt-mortgage.us.* families

US tax forms (W-2, 1098, 1099 variants, 1040) and mortgage documents (1003, 1008, closing disclosure).

Add-on capabilities are enabled per request with features=: ocrHighResolution, formulas, styleFont, barcodes, languages, keyValuePairs and queryFields (ask for extra fields by name without training). Layout and read can also return a searchable PDF (output=pdf).

Source: Document Intelligence model overview

Limits and formats

  • Formats: PDF, JPEG, PNG, BMP, TIFF, HEIF; DOCX, XLSX, PPTX and HTML for read and layout only.

  • S0: files up to 500 MB and 2,000 pages. F0: 4 MB and the first 2 pages.

  • Rate: 15 analyze requests per second by default; 50 get-result requests per second.

  • Results are kept for 24 hours after analysis, then deleted.

Source: Document Intelligence service limits

Provisioning

In the Azure portal

  1. Use the Foundry resource foundry-bookshelf, or create a single-service FormRecognizer resource if you need a commitment tier or containers.

  2. Open Document Intelligence Studio (https://documentintelligence.ai.azure.com/studio) and select the resource to try read, layout and every prebuilt model on your own files, and to label custom models. The Foundry portal’s Vision + Document playground offers the same prebuilt models.

  3. Assign Cognitive Services User on the resource to the job’s managed identity, and Storage Blob Data Reader on stbookshelf so the job can read the blobs.

  4. Document Intelligence downloads a urlSource itself, without the caller’s identity, so a private blob URL fails. Either send the file’s bytes (the job reads the blob with its own identity, as the end-to-end invoice pipeline does), or pass a short-lived read-only user delegation SAS URL, as below.

With the Azure CLI

az storage container create --account-name stbookshelf --name invoices --auth-mode login

az role assignment create \
  --assignee "$(az identity show --name id-orders-api --resource-group "$RG" --query principalId -o tsv)" \
  --role "Cognitive Services User" \
  --scope "$(az cognitiveservices account show --name "$FOUNDRY" --resource-group "$RG" --query id -o tsv)"

Source: Create a Document Intelligence resource

The examples below pass the invoice as a read-only user delegation SAS URL, signed with your Entra identity (it needs a data role such as Storage Blob Data Reader on stbookshelf) and valid for one hour:

INVOICE_URL=$(az storage blob generate-sas \
  --account-name stbookshelf --container-name invoices --name acme-2026-0917.pdf \
  --permissions r --expiry "$(date -u -d '+1 hour' '+%Y-%m-%dT%H:%MZ')" \
  --auth-mode login --as-user --full-uri -o tsv)
export INVOICE_URL

Source: Create a user delegation SAS with the Azure CLI

The asynchronous analyze pattern

Every analyze call is a long-running operation:

sequenceDiagram participant C as Client participant DI as Document Intelligence C->>DI: POST documentModels/prebuilt-invoice:analyze DI-->>C: 202 Accepted with Operation-Location header loop Until status is succeeded or failed C->>DI: GET Operation-Location DI-->>C: status running end DI-->>C: status succeeded with analyzeResult

With curl:

TOKEN=$(az account get-access-token --resource https://cognitiveservices.azure.com --query accessToken -o tsv)

OP=$(curl -s -i -X POST \
  "https://$FOUNDRY.cognitiveservices.azure.com/documentintelligence/documentModels/prebuilt-invoice:analyze?api-version=2024-11-30&features=queryFields&queryFields=PurchaseOrderRef" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"urlSource\":\"$INVOICE_URL\"}" \
  | grep -i '^operation-location' | cut -d' ' -f2 | tr -d '\r')

until [ "$(curl -s "$OP" -H "Authorization: Bearer $TOKEN" | jq -r .status)" != "running" ]; do sleep 2; done
curl -s "$OP" -H "Authorization: Bearer $TOKEN" | jq '.analyzeResult.documents[0].fields.InvoiceTotal'

Source: Document Intelligence REST quickstart

The SDKs wrap the polling in a poller:

import os
from azure.ai.documentintelligence import DocumentIntelligenceClient
from azure.ai.documentintelligence.models import AnalyzeDocumentRequest
from azure.identity import DefaultAzureCredential

client = DocumentIntelligenceClient(
    "https://foundry-bookshelf.cognitiveservices.azure.com/", DefaultAzureCredential()
)
poller = client.begin_analyze_document(
    "prebuilt-invoice",
    AnalyzeDocumentRequest(url_source=os.environ["INVOICE_URL"]),  # user delegation SAS URL
)
invoice = poller.result().documents[0]
for name in ("VendorName", "InvoiceId", "InvoiceTotal"):
    field = invoice.fields.get(name)
    print(name, field.content if field else None, field.confidence if field else None)
for item in invoice.fields["Items"].value_array:
    print(item.value_object["Description"].content, item.value_object["Amount"].content)

Source: Document Intelligence quickstart (Python)

using Azure;
using Azure.AI.DocumentIntelligence;
using Azure.Identity;

var client = new DocumentIntelligenceClient(
    new Uri("https://foundry-bookshelf.cognitiveservices.azure.com/"), new DefaultAzureCredential());

Operation<AnalyzeResult> operation = await client.AnalyzeDocumentAsync(
    WaitUntil.Completed, "prebuilt-invoice",
    new Uri(Environment.GetEnvironmentVariable("INVOICE_URL")!)); // user delegation SAS URL

AnalyzedDocument invoice = operation.Value.Documents[0];
if (invoice.Fields.TryGetValue("InvoiceTotal", out DocumentField total))
    Console.WriteLine($"{total.ValueCurrency.Amount} {total.ValueCurrency.CurrencyCode} ({total.Confidence:P0})");

Source: Document Intelligence quickstart (C#)

import com.azure.ai.documentintelligence.DocumentIntelligenceClient;
import com.azure.ai.documentintelligence.DocumentIntelligenceClientBuilder;
import com.azure.ai.documentintelligence.models.*;
import com.azure.identity.DefaultAzureCredentialBuilder;

DocumentIntelligenceClient client = new DocumentIntelligenceClientBuilder()
    .endpoint("https://foundry-bookshelf.cognitiveservices.azure.com/")
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

AnalyzeResult result = client.beginAnalyzeDocument("prebuilt-invoice",
        new AnalyzeDocumentOptions(System.getenv("INVOICE_URL"))) // user delegation SAS URL
    .getFinalResult();

DocumentField total = result.getDocuments().get(0).getFields().get("InvoiceTotal");
System.out.println(total.getContent() + " " + total.getConfidence());

Source: Document Intelligence quickstart (Java)

Bookshelf: supplier-invoice pipeline

Publishers and distributors email PDF invoices, which an operator drops into the invoices container in stbookshelf. An Event Grid subscription on BlobCreated starts a Container Apps job, invoice-processor, which:

  1. analyzes the blob with prebuilt-invoice (plus the PurchaseOrderRef query field)

  2. sends any field under 0.8 confidence to a review queue

  3. posts the vendor, invoice ID, purchase order, line items and total to orders-api (POST /supplier-invoices)

  4. tags the blob as processed

The end-to-end version, with PII redaction and Bicep, is on End-to-End Scenarios: Combining Foundry Tools. For document types without a prebuilt model, compare custom models (Document Intelligence: Custom Models, Classification and RAG Ingestion) with Content Understanding; the comparison figure is on Content Understanding: Multimodal Analyzers.

Use cases

Scenario Feature Why this feature Example input → output

Bookshelf: supplier invoices from the invoices container

prebuilt-invoice + queryFields

Fixed fields with confidence; deterministic; runs unattended.

acme-2026-0917.pdf → vendor, PO, 14 line items, total 1,284.50 EUR → orders-api

Accounts-payable automation

prebuilt-invoice

Hundreds of vendor layouts without training.

Invoice PDF → ERP record

Expense receipts

prebuilt-receipt

Photos taken on phones; tips and taxes.

Receipt photo → merchant, date, total

KYC ID capture

prebuilt-idDocument

Passport and license fields, including MRZ.

Passport scan → name, number, expiry

Loan and mortgage packages

prebuilt-mortgage.us.*, classifier first

Mixed packets of standard forms.

120-page packet → fields per form

Insurance claims

prebuilt-layout + queryFields

Free-form claim letters with a few key fields.

Claim letter → policy number, incident date

When not to use it

  • When the fields need reasoning across the document (for example "the effective renewal date given the notice clause"), Content Understanding or a Foundry Model fits better.

  • For OCR of photos with captions and tags in one call, Image Analysis does both until 2028-09-25.

  • See Choosing a Foundry Tool (or a Foundry Model).

Clean up

az storage container delete --account-name stbookshelf --name invoices --auth-mode login

Source: Azure CLI reference — az storage container delete

Related pages

References