Microsoft has set a hard end-of-service date for Azure AI Document Intelligence v2.0: August 31, 2026. The clock is now ticking for organizations that still rely on the older API to process invoices, receipts, identity documents, or custom forms. But while the retirement message is clear, the migration path is not a simple choice between “move to v4.0” and “wait.” Admins, developers, and automation owners need to understand exactly what’s being retired, what stays online, and why the latest version may not be the right fit for every workload—especially those running in containers or deeply embedded in Windows-based processes.

The August 2026 Deadline Is Just the Start

The key date is August 31, 2026, but it doesn’t apply universally. Microsoft’s documentation draws a line between the v2.0 cloud API (which shuts down on that date) and the v2.1 cloud REST API, which remains supported until September 15, 2027. The v2.1 container, however, also reaches end of support on August 31, 2026. The distinction matters because many Windows shops run a mix of cloud-hosted services and self-hosted Docker containers, often with overlapping responsibilities. A Power Automate flow may call the cloud endpoint while a local Windows Server instance runs the container for high-volume processing or data-residency reasons. If you treat the retirement notice as a single event, you risk leaving v2.1 containers running past their supported window—or, conversely, rushing to replace a v2.1 cloud integration that still has a year of breathing room.

This staggered timeline gives teams a critical window to plan deliberately rather than react in panic. But it also creates a false sense of safety: 2027 may seem distant, yet the deeper you look, the more you’ll find hidden dependencies on API versions, response shapes, and model behaviors that won’t survive a hasty upgrade.

What Exactly Is Being Retired

Azure AI Document Intelligence (formerly Form Recognizer) has evolved through several major API versions:

  • v2.0 (cloud API) — end of service: August 31, 2026
  • v2.1 (container) — end of support: August 31, 2026
  • v2.1 (cloud REST API) — end of support: September 15, 2027
  • v3.0 (cloud API) — end of support: March 30, 2029
  • v3.1 — GA, no retirement date announced
  • v4.0 — current GA, no retirement date announced

The v4.0 API (2024-11-30) is Microsoft’s recommended target for new development. It introduces a modern REST contract under the documentintelligence/documentModels route family, diverging from the older formrecognizer/v2.x pattern. v3.1 (2023-07-31) remains fully supported and offers a more conservative path for teams that can’t yet adopt the v4.0 contract or need broader container model support.

A Fork in the Road: v3.1 vs. v4.0

Microsoft’s recommendation is clear: “Use Azure Document Intelligence 2024-11-30 v4.0 for all new development, and migrate existing workloads to v4.0 before the retirement dates.” But operational reality often forks that guidance.

Choose v3.1 when:
- You depend on container models beyond Read and Layout. v4.0 containers support only those two; v3.1 containers add ID Document, Receipt, and Invoice.
- Your workflows are stable and rely on established extraction contracts, output schemas, or polling patterns that would be expensive to rewrite.
- You run on-premises invoice or receipt processing that cannot be moved to the cloud and uses a container with specific model coverage.
- You need a near-term migration with the lowest regression risk.

Choose v4.0 when:
- You are building new cloud-native document services, Azure Functions, or .NET integrations.
- You can adopt the modern REST path and are willing to redesign result parsing from scratch.
- You want the freshest features, improved accuracy, and all the latest prebuilt model enhancements.
- Container support for Read and Layout is sufficient for your local workloads.

The decision should be made per workload, not per subscription. One organization can standardize on v4.0 for greenfield cloud development while keeping a containerized invoice pipeline on v3.1 indefinitely—at least until v3.1 receives its own retirement notice.

Why a Simple Version Bump Can Break Your Workflows

The difference between v2.x and the newer APIs isn’t cosmetic. It’s a structural change in how you submit documents, poll for results, and interpret the output. A typical v2.x caller uses paths like formrecognizer/v2.0/custom/models/{modelId}/analyze and expects a response where analyzed fields live under analyzeResult.documentResults[0].fields. A v4.0 caller sends a request to documentintelligence/documentModels/{modelId}:analyze and gets back a document-centric result set that requires different traversal logic.

If you simply swap the endpoint URL and update the SDK nuget, your parser may silently break. A downstream SQL stored procedure, a Power Automate expression, or a C# mapping class that expects a property like analyzeResult.documentResults will fail, either throwing an error or worse, producing garbled or missing data without alerting anyone. In Windows automation environments, these parsers are often scattered across Azure Functions, PowerShell scripts, IIS-hosted services, and desktop utilities—making the inventory step far more important than picking a version number.

Container workloads add another layer. The v2.1 container retirement forces a change to v3.1 or v4.0 containers, but v4.0’s limited model support may drop your existing invoice processing entirely. Before pulling a new Docker image, confirm that your model is listed as supported. Otherwise, you’ll be forced to v3.1 or even v3.0 (if you need all models, though v3.0 itself retires in 2029).

Where to Look Before You Migrate

Discovery is the first and most time-consuming step. Because Document Intelligence was originally named Form Recognizer, legacy code, configuration files, and custom connectors often reference the old name. You must search not just for “Document Intelligence” but also for “formrecognizer,” “form.recognizer,” and “analyzeResults.” Scan these locations:

  • Azure Functions application settings and connection strings
  • IIS web.config and environment variables
  • PowerShell scripts that call REST endpoints directly
  • Windows Task Scheduler actions that trigger scripts or executables
  • Power Automate flows with HTTP actions or custom connectors
  • Key Vault secrets storing API keys or endpoint URLs
  • Docker Compose files and container orchestration manifests

For every hit, record the full endpoint URL, the model ID being used, the deployment mode (cloud vs. container), and the downstream consumer of the response. A receipt workflow isn’t “working” just because the API returns a 200 status; it must supply the correct vendor name, totals, and line items to your accounting system. If any consumer normalizes fields differently, you need to know.

Power Automate merit extra scrutiny. Flows may use the legacy “Form Recognizer” connector or a generic HTTP action pointed at v2.x endpoints. Expressions within those flows may dip into deep JSON properties like body('analyzeResult')['documentResults'][0]['fields']['Total']['value']. When the response schema changes, these expressions break silently—the flow continues to run but fails to insert data into the right column. Test not just the API call but the entire flow from trigger to final business action.

Action Plan: Steps to Move Safely

Once you’ve inventoried your endpoints and consumers, follow these steps to execute the migration without disrupting operations:

  1. Assign a target version per workload. Based on container requirements, model coverage, and output consumers, decide whether to move each integration to v3.1 or v4.0. Document the rationale.
  2. Introduce a mapping layer. Instead of letting raw API responses flow directly into business logic, create an internal contract (e.g., InvoiceRecord, ReceiptRecord) and map the API result to it. This isolates your downstream code from API changes and makes it easier to test and compare versions.
  3. Run dual-version tests. Spin up the new integration in parallel, pointing at the same set of test documents. Compare the mapped business objects, not the raw JSON. Verify that absent values, confidence scores, and table structures are handled consistently.
  4. Test the full operational path. Don’t stop at extraction. Verify that the document processing pipeline—polling, timeout handling, retries, error alerts, database inserts, approval queues—works with the new API and container.
  5. Plan a rollback strategy. For scripts moving off v2.0, the fallback can’t be “switch back to v2.0” after the deadline. Instead, maintain the old parser alongside the new one until you’re confident. If the new parser fails, route traffic back to the v3.1 or v4.0 implementation (not the retired v2.x).
  6. Check regional availability and cost. v4.0 may have different regional availability than v2.x, and add-on features like formulas, high resolution, or searchable PDF may incur extra costs. Validate in the Azure portal and estimate expenses based on your document mix.

The Bigger Picture

This retirement isn’t an isolated event. Microsoft is actively retiring older Azure AI APIs—the Computer Vision v2.0 preview, for instance, is on a similar path. The pattern repeats: endpoint discovery, contract analysis, careful version selection. For Windows professionals managing a fleet of automation tools, the lesson is to treat API versioning as a lifecycle problem, not an upgrade afterthought.

The v2.0 and v2.1 container deadline arrives in less than a year and a half. That’s enough time to inventory every hidden dependency, but only if you start now. Waiting until Q2 2026 will force rushed decisions that break extraction pipelines at the worst possible moment.

If your workloads depend on the v2.1 cloud endpoint, the extra year until 2027 is a gift—don’t waste it. Use the time to gradually transition to v3.1 or v4.0 on your own terms, and retire the old API with confidence, not urgency.