Azure Document Intelligence v2.0 retires 31 August 2026: three Microsoft pages, three different migration targets

Summary. Azure AI Document Intelligence v2.0 is retired on 31 August 2026, which is 14 days from this update. The retirement notice, published 15 September 2023 and never revised, tells you to "transition to Azure AI Document Intelligence v3.1 API by that date". The Microsoft Learn version page, carrying an ms.date of 11 June 2026, does not mention v2.0 anywhere: it lists only two retirements, v2.1 on 15 September 2027 and v3.0 (2022-08-31) on 30 March 2029, and tells you to use 2024-11-30 v4.0 for all new development. The v4.0 migration guide, dated 21 May 2026, repeats the same two dates and is also silent on v2.0. Three official Microsoft surfaces, two different answers, and a hard cutover in a fortnight. If you run invoice or KYC extraction on the /formrecognizer/v2.0/ endpoints, the practical answer is v4.0, and the reason is a retraining cost you pay once rather than twice.

What is actually retiring, and what is not

The retiring artefact is the REST API surface at https://{endpoint}/formrecognizer/v2.0/..., together with the v2.0 client libraries that call it. Microsoft's v4.0 migration guide sets out the URL shape that is going away:

Two things follow from that table. First, v2.0 never had an invoice or ID-document prebuilt model, so anyone doing invoice or KYC extraction on v2.0 is doing it with a custom model, and custom models are the expensive part of this migration. Second, the v3.x path structure is a genuine redesign, not a version bump: the per-model endpoints collapse into one documentModels/{modelId} pair. Client code that builds URLs by string concatenation will not survive.

The retirement does not touch v2.1. Microsoft's What's new page gives v2.1 an end-of-support date of 15 September 2027, thirteen months later. We have seen the claim that the v2.1 container image also stops on 31 August 2026; no Microsoft page we could retrieve states that, so treat it as unverified and confirm it against your own support contact before you plan around it.

Why the two answers exist

The retirement notice was written in September 2023. At that point v3.1 was the current GA API and v4.0 did not exist; the 2024-11-30 GA release landed in November 2024 and the GA client libraries in December 2024. Azure retirement notices are dated artefacts and are not revised as the product moves on, so the notice still recommends the API that was newest three years ago. Nothing about the notice is wrong. It is stale.

The Learn documentation reflects the current position. Its "Important" box on both the What's new page and the migration guide is identical, and it does not list v2.0 because a retirement two weeks out is no longer a planning horizon Microsoft documents. The absence is not a reprieve.

The practical reading: the notice tells you the deadline, the docs tell you the destination.

v3.1 or v4.0: the effort and cost comparison

Both targets require the same endpoint rewrite, because the v3.x URL redesign is shared. The difference is what happens after.

That table is the whole argument. Microsoft's custom neural model page, last updated 15 August 2026, is explicit: on v3.1 (2023-07-31) and v3.0 (2022-08-31) "you receive a maximum 30 minutes of training duration per model, and a maximum of 20 trainings for free per month", and paid training "isn't enabled". On v4.0 you get 10 hours of free model training and can set maxTrainingHours up to 10 on a single build. If your KYC or invoice model needs more than half an hour to converge on a real dataset, v3.1 cannot train it for free and cannot train it for money either.

The real cost is the migration, not the code. You will retrain the model whichever target you pick, so pick the one that does not make you retrain again.

The four traps that break v2.0 migrations

1. Custom models expire, and they expire against a base model you do not control

Document Intelligence custom extraction and classification models are built on a periodically updated base model, and every custom model now carries an expirationDateTime in its GET /documentModels/{customModelId} response. Microsoft's migration guide is blunt about the preview case: custom models trained on a preview API version "are tied to that preview API version's lifecycle and base model", and retire with it. Query every model ID in your subscription for its expiry before you plan the cutover, not after.

2. boundingBox was renamed to polygon

The 2023-07-31 REST release "includes a breaking change in the REST API analyze response JSON": boundingBox is renamed to polygon in each instance. Any downstream code that draws overlays, computes field positions, or stores coordinates for audit will silently read undefined rather than fail loudly. Grep for the string before you deploy.

3. includeTextDetails is gone and the response shape moved

The pages collection is no longer a property nested under a result object; pages, tables, keyValuePairs, entities, styles and documents are all top-level properties of analyzeResult. The includeTextDetails parameter is no longer supported, because the full output is always returned. pages and locale still work.

4. Custom classification no longer splits documents by default

Under v4.0 the custom classification model "doesn't split documents by default during analysis"; you must set splitMode to auto to keep the older behaviour. A multi-page KYC pack that used to arrive as separate classified documents will arrive as one. This is the failure that looks like a model accuracy regression and is not.

The SDK rename is where the compiler helps you

The client libraries changed class names, not just versions, which means the migration surfaces as compile errors rather than runtime surprises. Microsoft's SDK overview, ms.date 6 May 2026, maps them:

The v4.0 GA packages are Azure.AI.DocumentIntelligence 1.0.0 on NuGet, com.azure:azure-ai-documentintelligence 1.0.0 on Maven, @azure-rest/ai-document-intelligence 1.0.0 on npm and azure-ai-documentintelligence 1.0.0 on PyPI. Note the package name change: the old libraries were Form Recognizer packages, so this is a new dependency rather than a version bump, and the old one will keep resolving in your lockfile until you remove it. One more constraint worth catching early: regional endpoints do not support Microsoft Entra authentication, so a resource without a custom subdomain cannot use DefaultAzureCredential and is stuck on API keys.

A 14-day cutover plan that fits the deadline

1. Inventory the calls. Grep the codebase and API Management policies for /formrecognizer/v2.0. Include batch jobs, Logic Apps and anything scheduled monthly that will not fire before 31 August.

1. Enumerate custom models. GET /documentModels?api-version=2024-11-30 returns prebuilt and custom models; prebuilt names start with prebuilt-. Record apiVersion and expirationDateTime for each custom model.

1. Retrain against `2024-11-30` first. Set buildMode to neural and, if the dataset is large, maxTrainingHours. Training data limits on v4.0 are 50,000 pages for custom neural extraction and 1 GB with a maximum of 10,000 pages for custom classification.

1. Check your region. Custom neural training runs in a fixed region list that includes Central India, East US, West Europe, UK South and Southeast Asia. A model trained in one of those can be copied to any other region using authorizeCopy followed by copyTo, and authorizeCopy is now a POST.

1. Diff the fields, not the confidence. Compare v2.0 and v4.0 extractions on the same 200-document sample and diff field-by-field. v4.0 adds table, row and cell confidence, so you can set thresholds per cell rather than per document.

1. Cut over behind a flag and keep the v2.0 path callable until 31 August, so a bad extraction reverts in one deploy rather than one release cycle.

What v4.0 gives you that pays for the work

Batch analysis takes up to 10,000 documents in a single request against a blob container, writing .ocr.json results into a result container, with succeeded, failed, skipped and notStarted per document. Two limits matter operationally: batch status is retained for only 24 hours after completion, and analysis results are not returned for individual files until the whole batch finishes, so monitor the *.ocr.json files landing in the result container if you need progress. Authorisation is by managed identity or SAS, and the source container needs read, write, list and delete while the result container needs write, list and delete.

For anyone processing personal documents, the delete-analyze-response API matters more than the throughput. Analyze responses are stored for 24 hours after the operation completes; v4.0 lets you delete the response sooner, explicitly for privacy compliance. On v2.0 you cannot.

India-specific considerations

KYC extraction on Indian identity documents sits directly under the Digital Personal Data Protection Act 2023. Section 16(1) gives the Central Government a power to restrict transfers by notification to named countries, which is a negative-list mechanism rather than blanket localisation. The DPDP Rules 2025, notified as G.S.R. 846(E) on 14 November 2025, add the harder hook at Rule 13(4): a Significant Data Fiduciary must ensure that personal data specified by the Central Government, and its traffic data, is not transferred outside India. Most of the substantive rules, including Rules 5 to 16, commence eighteen months after publication. Penalties reach ₹250 crore for failure to maintain reasonable security safeguards, per the Press Information Bureau summary.

Two consequences for this migration. Custom neural training is available in Central India, so an Indian financial-services workload can train and serve in-country without the copy step. And the v4.0 delete-analyze-response API gives you a defensible answer to a data-minimisation question that v2.0 simply cannot answer, because on v2.0 the 24-hour retention is not shortenable by the caller. If you are working through the wider obligations, our DPDP Act engineering playbook covers the architecture side, and the DPDP compliance cost breakdown covers the budget side.

How this fits the rest of the Azure retirement wave

v2.0 is not an isolated event. The Anomaly Detector and Personalizer retirements hit the same Azure AI services estate, the Azure OpenAI Assistants to Foundry Agents migration hits the same teams, and the AzureRM 5.0 provider upgrade hits the Terraform that deploys all of it. If three of those land in the same quarter, sequence them against a single regression suite rather than three, and read them against the cloud FinOps view so the retraining spend lands in a budget line someone owns.

FAQ

How eCorpIT can help

eCorpIT runs Azure AI and cloud modernisation work for teams in India, the UK and the US, and this class of migration — endpoint rewrite, custom-model retrain, field-level regression diffing — is the shape of engagement we take on most often. Founded in 2021 and based in Gurugram, we are CMMI Level 5, MSME certified and ISO 27001:2022 certified, and a Microsoft partner. We design document-processing pipelines aligned with DPDP Act 2023 requirements, including in-country training regions and explicit response deletion. If a 31 August cutover is looking tight, talk to us about a scoped two-week migration, or look at how we approach Azure landing zone and Terraform modernisation and API integration modernisation.

References

1. Retirement: Azure AI Document Intelligence v2.0 API will be retired on 31 August 2026 — Microsoft Azure Updates release-communications feed, pubDate 15 September 2023.

1. What's new in Azure Document Intelligence — Microsoft Learn, ms.date 11 June 2026.

1. Document Intelligence v4.0 migration — Microsoft Learn, ms.date 21 May 2026.

1. Document Intelligence custom neural model — Microsoft Learn, last updated 15 August 2026.

1. Document Intelligence batch analysis — Microsoft Learn, last updated 18 May 2026.

1. Azure updates — Microsoft Azure, canonical home of the retirement notice.

1. SDK target: REST API v4.0 (GA) — Microsoft Learn, ms.date 6 May 2026.

1. Digital Personal Data Protection Act 2023 — Ministry of Electronics and Information Technology.

1. Digital Personal Data Protection Rules 2025, G.S.R. 846(E) — MeitY, notified 14 November 2025.

1. DPDP Rules 2025 summary and penalties — Press Information Bureau, November 2025.

Last updated: 17 August 2026.