Azure AI Document Intelligence API version 2.0 retires on 31 August 2026. The product may be known internally as Form Recognizer or Document Intelligence, but the name is not enough to establish risk. The API version in the actual request is what matters.
Why the deadline can be easy to miss
Document Intelligence is the current name for the Azure service previously called Form Recognizer. It extracts text, tables, key-value pairs and structured fields from documents so another system can process them. Typical business uses include invoices, receipts, application forms, identity documents and document classification.
A workflow can be described as “Document Intelligence” while its code still calls the older /formrecognizer/v2.0 endpoint. A vendor screen may show the current product name while a connector, function, script or software development kit still uses the retired API. The Azure resource itself can remain available while one application path is exposed.
Microsoft lists the v2.0 API and the v2.1 Document Intelligence container for retirement on 31 August 2026. Do not confuse those with the hosted v2.1 REST API, which Microsoft currently lists for end of support on 15 September 2027. Version 3.0 has a different published date. The inventory must therefore record the exact API or container version, not only the service name.
What can change during migration
Microsoft recommends version 4.0, identified by the 2024-11-30 API version, for new development and provides a migration route from v2.0 and v2.1. This is not always a one-line configuration change.
From version 3.0, Microsoft redesigned the REST API. Layout, prebuilt and custom model operations use a consolidated document-model pattern. Request paths change. Model identifiers change. The result format is reorganised around pages, tables, key-value pairs, entities, styles and documents.
Field names and locations can also change. Microsoft’s migration guide notes that boundingBox becomes polygon in newer response structures. Some parameters, including includeTextDetails, are no longer supported because the full output is returned. Application code that parses the old response can therefore fail even when the new analysis call succeeds.
Custom models need their own review. Model construction, composition, copy operations and metadata differ across versions. Preview-trained models can also be tied to the lifecycle of the preview API and base model that created them. The safe migration checks the API call, model, response parser and downstream business rules together.
Map the technical call to the business process
An API inventory has limited value until it identifies the process behind each call. One endpoint may support supplier invoice capture. Another may read customer application forms. A third may extract identifiers used by a compliance workflow. The business impact differs even if the technical service is the same.
For every dependency, record the Azure resource, subscription, region, endpoint, API version, software development kit, model ID, source application, document types, monthly volume, process owner and downstream destination. Include who handles exceptions and where failed documents wait for manual review.
Search more than application code. API versions can appear in environment variables, integration-platform connectors, Azure Functions, Logic Apps, container configurations, infrastructure templates, vendor configuration, secrets and diagnostic logs. A production dependency can survive long after the developer who created it has left.
Test business outputs, not only HTTP success
A successful response proves that the service answered. It does not prove that an invoice posts correctly, a form reaches the right case or a confidence threshold still sends the right documents for manual review.
Build a fixed regression set containing ordinary documents, poor scans, handwritten content, multi-page files, rotated pages, missing fields, duplicate invoices and known exceptions. Keep the expected output for each document. Run the same set through the old and target versions, then compare both the extracted data and the business result.
Check field names, data types, normalised values, confidence scores, page references, table structures, selection marks and error responses. Validate mapping into the downstream system. Reconcile a sample of totals and identifiers. Confirm how retries, timeouts, throttling and failed analyses are handled. Microsoft recommends at least a one-second interval when polling an analysis result.
Where model quality changes, better extraction can still alter a downstream decision. A field that was previously blank may now be populated. A currency may be normalised differently. Treat those changes as controlled application behaviour, not automatically as an improvement.
Decision owner
Primary owner: The application integration owner owns the API migration. The Azure platform owner confirms resources and controls. Developers update code and models. Process owners validate documents, exceptions and downstream outcomes.
Action within seven days
- Day 1: Search code, endpoints, configuration, connectors and logs for
v2.0and legacy Form Recognizer paths. - Day 2: Map each call to its Azure resource, application, model, document type, process and owner.
- Day 3: Separate v2.0 API use from v2.1 REST, v2.1 container, v3.x and preview dependencies.
- Day 4: Select the supported target and identify endpoint, SDK, model and response-schema changes.
- Day 5: Build the regression set and expected results from real, sanitised business documents.
- Day 6: Run side-by-side tests and reconcile extraction, exceptions and downstream postings.
- Day 7: Approve cutover, monitoring and rollback plans. Escalate every unowned or untested dependency.
Evidence to retain
- The dated dependency inventory with exact API version, resource, application and owner.
- The code, configuration or connector change identifying the new endpoint and SDK.
- The fixed regression set, expected output and document-handling controls.
- Before-and-after extraction results with field and confidence comparisons.
- Downstream reconciliation, exception evidence and business-owner sign-off.
- The cutover record, monitoring dashboard, rollback procedure and post-release review.
Questions decision-makers are asking
Is Form Recognizer different from Document Intelligence?
Document Intelligence is the current name for the service previously called Form Recognizer. The name change does not prove that an application uses a supported API. Inspect the endpoint, API-version parameter, SDK and container version used by the running workload.
Does the 31 August deadline apply to every version?
No. Microsoft lists the v2.0 API and the v2.1 container for 31 August 2026. The hosted v2.1 REST API and later versions have different published support dates. Record the exact interface before deciding the urgency or migration route.
Can developers point the old code at version 4.0?
Not safely without testing. Newer versions change endpoint patterns, model identifiers and response structures. Downstream parsing and business rules may rely on old field names or locations. Follow Microsoft’s migration guide and validate representative documents end to end.
What is the minimum acceptable migration test?
Use a fixed set of real, sanitised documents covering normal cases and known exceptions. Compare extracted fields, data types, confidence, page references, errors and downstream results. Obtain sign-off from the process owner, not only the developer who changed the call.
The Braintree view
The largest risk is version ambiguity. A product name, Azure resource or vendor assurance is not enough. The control is an evidence-backed map from the exact request to the business outcome it supports.
Read how Braintree approaches Azure application modernisation, use the Braintree Briefing episode to align decision owners, then speak to a Braintree specialist to scope the inventory and regression plan.
