Form Recognizer SDKs

This article applies to: Form Recognizer v3.0. Form Recognizer v2.1.

Azure Cognitive Services Form Recognizer is a cloud service that uses machine learning to analyze text and structured data from documents. The Form Recognizer software development kit (SDK) is a set of libraries and tools that enable you to easily integrate Form Recognizer models and capabilities into your applications. Form Recognizer SDK is available across platforms in C#/.NET, Java, JavaScript, and Python programming languages.

Supported languages

Form Recognizer SDK supports the following languages and platforms:

Language → SDK version	Package	Azure Form Recognizer SDK	Supported API version	Platform support
.NET/C# → 4.0.0 (latest GA release)	Azure SDK for .NET	v3.0 v2.1 v2.0	Windows, macOS, Linux, Docker
Java → 4.0.0 (latest GA release)	Azure SDK for Java	v3.0 v2.1 v2.0	Windows, macOS, Linux
JavaScript → 4.0.0 (latest GA release)	npm	Azure SDK for JavaScript	v3.0 v2.1 v2.0	Browser, Windows, macOS, Linux
Python → 3.2.0 (latest GA release)	PyPI	Azure SDK for Python	v3.0 v2.1 v2.0	Windows, macOS, Linux

Supported Clients

Language	SDK version	API version	Supported clients
C# /.NET Java JavaScript	4.0.0 (latest GA release)	v3.0 (default)	DocumentAnalysisClient DocumentModelAdministrationClient
C# /.NET Java JavaScript	4.0.0 (latest GA release)	v2.1 v2.0	FormRecognizerClient FormTrainingClient
C# /.NET Java JavaScript	3.1.x	v2.1 (default) v2.0	FormRecognizerClient FormTrainingClient
C# /.NET Java JavaScript	3.0.x	v2.0	FormRecognizerClient FormTrainingClient
Python	3.2.0 (latest GA release)	v3.0 (default)	DocumentAnalysisClient DocumentModelAdministrationClient
Python	3.2.0 (latest GA release)	v2.1 v2.0	FormRecognizerClient FormTrainingClient
Python	3.1.x	v2.1 (default) v2.0	FormRecognizerClient FormTrainingClient
Python	3.0.0	v2.0	FormRecognizerClient FormTrainingClient

Use Form Recognizer SDK in your applications

The Form Recognizer SDK enables the use and management of the Form Recognizer service in your application. The SDK builds on the underlying Form Recognizer REST API allowing you to easily use those APIs within your programming language paradigm. Here's how you use the Form Recognizer SDK for your preferred language:

1. Install the SDK client library

C#/.NET

dotnet add package Azure.AI.FormRecognizer --version 4.0.0-beta.5

Install-Package Azure.AI.FormRecognizer -Version 4.0.0-beta.5

Java

    <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-formrecognizer</artifactId>
    <version>4.0.0-beta.5</version>
    </dependency>

implementation("com.azure:azure-ai-formrecognizer:4.0.0-beta.5")

JavaScript

npm i @azure/ai-form-recognizer@4.0.0-beta.6

Python

pip install azure-ai-formrecognizer==3.2.0b6

2. Import the SDK client library into your application

C#/.NET

using Azure;
using Azure.AI.FormRecognizer.DocumentAnalysis;

Java

import com.azure.ai.formrecognizer.*;
import com.azure.ai.formrecognizer.models.*;
import com.azure.ai.formrecognizer.DocumentAnalysisClient.*;

import com.azure.core.credential.AzureKeyCredential;

JavaScript

const { AzureKeyCredential, DocumentAnalysisClient } = require("@azure/ai-form-recognizer");

Python

from azure.ai.formrecognizer import DocumentAnalysisClient
from azure.core.credentials import AzureKeyCredential

3. Set up authentication

There are two supported methods for authentication

• Use a Form Recognizer API key with AzureKeyCredential from azure.core.credentials.

• Use a token credential from azure-identity to authenticate with Azure Active Directory.

Use your API key

Here's where to find your Form Recognizer API key in the Azure portal:

C#/.NET

//set `<your-endpoint>` and `<your-key>` variables with the values from the Azure portal to create your `AzureKeyCredential` and `DocumentAnalysisClient` instance
string key = "<your-key>";
string endpoint = "<your-endpoint>";
AzureKeyCredential credential = new AzureKeyCredential(key);
DocumentAnalysisClient client = new DocumentAnalysisClient(new Uri(endpoint), credential);

Java

// create your `DocumentAnalysisClient` instance and `AzureKeyCredential` variable
DocumentAnalysisClient client = new DocumentAnalysisClientBuilder()
            .credential(new AzureKeyCredential("<your-key>"))
            .endpoint("<your-endpoint>")
            .buildClient();

JavaScript

// create your `DocumentAnalysisClient` instance and `AzureKeyCredential` variable
async function main() {
    const client = new DocumentAnalysisClient("<your-endpoint>", new AzureKeyCredential("<your-key>"));

Python

# create your `DocumentAnalysisClient` instance and `AzureKeyCredential` variable
    document_analysis_client = DocumentAnalysisClient(endpoint="<your-endpoint>", credential=AzureKeyCredential("<your-key>"))

Use an Azure Active Directory (Azure AD) token credential

Note

Regional endpoints do not support AAD authentication. Create a custom subdomain for your resource in order to use this type of authentication.

Authorization is easiest using the DefaultAzureCredential. It provides a default token credential, based upon the running environment, capable of handling most Azure authentication scenarios.

C#/.NET

Here's how to acquire and use the DefaultAzureCredential for .NET applications:

1. Install the Azure Identity library for .NET:

       dotnet add package Azure.Identity
   

       Install-Package Azure.Identity
   

2. Register an Azure AD application and create a new service principal.

3. Grant access to Form Recognizer by assigning the Cognitive Services User role to your service principal.

4. Set the values of the client ID, tenant ID, and client secret in the Azure AD application as environment variables: AZURE_CLIENT_ID, AZURE_TENANT_ID, and AZURE_CLIENT_SECRET, respectively.

5. Create your DocumentAnalysisClient instance including the DefaultAzureCredential:

   string endpoint = "<your-endpoint>";
   var client = new DocumentAnalysisClient(new Uri(endpoint), new DefaultAzureCredential());
   

For more information, see Authenticate the client

Java

Here's how to acquire and use the DefaultAzureCredential for Java applications:

1. Install the Azure Identity library for Java:

   <dependency>
       <groupId>com.azure</groupId>
       <artifactId>azure-identity</artifactId>
       <version>1.5.3</version>
   </dependency>
   

2. Register an Azure AD application and create a new service principal.

3. Grant access to Form Recognizer by assigning the Cognitive Services User role to your service principal.

4. Set the values of the client ID, tenant ID, and client secret of the Azure AD application as environment variables: AZURE_CLIENT_ID, AZURE_TENANT_ID, and AZURE_CLIENT_SECRET, respectively.

5. Create your DocumentAnalysisClient instance and TokenCredential variable:

   TokenCredential credential = new DefaultAzureCredentialBuilder().build();
   DocumentAnalysisClient documentAnalysisClient = new DocumentAnalysisClientBuilder()
       .endpoint("{your-endpoint}")
       .credential(credential)
       .buildClient();
   

For more information, see Authenticate the client

JavaScript

Here's how to acquire and use the DefaultAzureCredential for JavaScript applications:

1. Install the Azure Identity library for JavaScript:

   npm install @azure/identity
   

2. Register an Azure AD application and create a new service principal.

3. Grant access to Form Recognizer by assigning the Cognitive Services User role to your service principal.

4. Set the values of the client ID, tenant ID, and client secret of the Azure AD application as environment variables: AZURE_CLIENT_ID, AZURE_TENANT_ID, and AZURE_CLIENT_SECRET, respectively.

5. Create your DocumentAnalysisClient instance including the DefaultAzureCredential:

   const { DocumentAnalysisClient } = require("@azure/ai-form-recognizer");
   const { DefaultAzureCredential } = require("@azure/identity");
   
   const client = new DocumentAnalysisClient("<your-endpoint>", new DefaultAzureCredential());
   

For more information, see Create and authenticate a client.

Python

Here's how to acquire and use the DefaultAzureCredential for Python applications.

1. Install the Azure Identity library for Python:

   pip install azure-identity
   

2. Register an Azure AD application and create a new service principal.

3. Grant access to Form Recognizer by assigning the Cognitive Services User role to your service principal.

4. Set the values of the client ID, tenant ID, and client secret of the Azure AD application as environment variables: AZURE_CLIENT_ID, AZURE_TENANT_ID, and AZURE_CLIENT_SECRET, respectively.

5. Create your DocumentAnalysisClient instance including the DefaultAzureCredential:

   from azure.identity import DefaultAzureCredential
   from azure.ai.formrecognizer import DocumentAnalysisClient
   
   credential = DefaultAzureCredential()
   document_analysis_client = DocumentAnalysisClient(
       endpoint="https://<my-custom-subdomain>.cognitiveservices.azure.com/",
       credential=credential
   )
   

For more information, see Authenticate the client

4. Build your application

You'll create a client object to interact with the Form Recognizer SDK, and then call methods on that client object to interact with the service. The SDKs provide both synchronous and asynchronous methods. For more insight, try a quickstart in a language of your choice.

Changelog and release history

Form Recognizer SDK September 2022 GA release

This release includes the following updates:

Important

The DocumentAnalysisClient and DocumentModelAdministrationClient now target API version v3.0 GA, released 2022-08-31. These clients are no longer supported by API versions 2020-06-30-preview or earlier.

C#

• Version 4.0.0 GA (2022-09-08)
• Supports REST API v3.0 and v2.0 clients

Package (NuGet)

Changelog/Release History

Migration guide

ReadMe

Samples

Java

• Version 4.0.0 GA (2022-09-08)
• Supports REST API v3.0 and v2.0 clients

Package (Maven)

Changelog/Release History

Migration guide

ReadMe

Samples

JavaScript

• Version 4.0.0 GA (2022-09-08)
• Supports REST API v3.0 and v2.0 clients

Package (npm)

Changelog/Release History

Migration guide

ReadMe

Samples

Python

Note

Python 3.7 or later is required to use this package.

• Version 3.2.0 GA (2022-09-08)
• Supports REST API v3.0 and v2.0 clients

Package (PyPi)

Changelog/Release History

Migration guide

ReadMe

Samples

Form Recognizer SDK beta August 2022 preview release

This release includes the following updates:

C#

Version 4.0.0-beta.5 (2022-08-09) Supports REST API 2022-06-30-preview clients

Changelog/Release History

Package (NuGet)

SDK reference documentation

Java

Version 4.0.0-beta.6 (2022-08-10) Supports REST API 2022-06-30-preview and earlier clients

Changelog/Release History

Package (Maven)

SDK reference documentation

JavaScript

Version 4.0.0-beta.6 (2022-08-09) Supports REST API 2022-06-30-preview and earlier clients

Changelog/Release History

Package (npm)

SDK reference documentation

Python

Important

Python 3.6 is no longer supported in this release. Use Python 3.7 or later.

Version 3.2.0b6 (2022-08-09) Supports REST API 2022-06-30-preview and earlier clients

Changelog/Release History

Package (PyPi)

SDK reference documentation

Form Recognizer SDK beta June 2022 preview release

This release includes the following updates:

C#

Version 4.0.0-beta.4 (2022-06-08)

Changelog/Release History

Package (NuGet)

SDK reference documentation

Java

Version 4.0.0-beta.5 (2022-06-07)

Changelog/Release History

Package (Maven)

SDK reference documentation

JavaScript

Version 4.0.0-beta.4 (2022-06-07)

Changelog/Release History

Package (npm)

SDK reference documentation

Python

Version 3.2.0b5 (2022-06-07

Changelog/Release History

Package (PyPi)

SDK reference documentation

Help options

The Microsoft Q&A and Stack Overflow forums are available for the developer community to ask and answer questions about Azure Form Recognizer and other services. Microsoft monitors the forums and replies to questions that the community has yet to answer. To make sure that we see your question, tag it with azure-form-recognizer.

Next steps

Try a Form Recognizer quickstart

Explore the Form Recognizer REST API v3.0