Share via

FormRecognizerClient Class

  • Reference

FormRecognizerClient extracts information from forms and images into structured data. It is the interface to use for analyzing with prebuilt models (receipts, business cards, invoices, identity documents), recognizing content/layout from forms, and analyzing custom forms from trained models. It provides different methods based on inputs from a URL and inputs from a stream.

Note

FormRecognizerClient should be used with API versions <=v2.1.

To use API versions 2022-08-31 and up, instantiate a DocumentAnalysisClient.

Inheritance
azure.ai.formrecognizer._form_base_client.FormRecognizerClientBase
FormRecognizerClient

Constructor

FormRecognizerClient(endpoint: str, credential: AzureKeyCredential | TokenCredential, **kwargs: Any)

Parameters

Name Description
endpoint
Required
str

Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus2.api.cognitive.microsoft.com).
credential
Required
AzureKeyCredential or TokenCredential

Credentials needed for the client to connect to Azure. This is an instance of AzureKeyCredential if using an API key or a token credential from identity.

Keyword-Only Parameters

Name Description
api_version
str or FormRecognizerApiVersion

The API version of the service to use for requests. It defaults to API version v2.1. Setting to an older version may result in reduced feature compatibility. To use the latest supported API version and features, instantiate a DocumentAnalysisClient instead.

Examples

Creating the FormRecognizerClient with an endpoint and API key.


   from azure.core.credentials import AzureKeyCredential
   from azure.ai.formrecognizer import FormRecognizerClient
   endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
   key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]

   form_recognizer_client = FormRecognizerClient(endpoint, AzureKeyCredential(key))

Creating the FormRecognizerClient with a token credential.


   """DefaultAzureCredential will use the values from these environment
   variables: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET
   """
   from azure.ai.formrecognizer import FormRecognizerClient
   from azure.identity import DefaultAzureCredential

   endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
   credential = DefaultAzureCredential()

   form_recognizer_client = FormRecognizerClient(endpoint, credential)

Methods

begin_recognize_business_cards

Extract field text and semantic values from a given business card. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff' or 'image/bmp'.

See fields found on a business card here: https://aka.ms/formrecognizer/businesscardfields

New in version v2.1: The begin_recognize_business_cards client method
begin_recognize_business_cards_from_url

Extract field text and semantic values from a given business card. The input document must be the location (URL) of the card to be analyzed.

See fields found on a business card here: https://aka.ms/formrecognizer/businesscardfields

New in version v2.1: The begin_recognize_business_cards_from_url client method
begin_recognize_content

Extract text and content/layout information from a given document. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff' or 'image/bmp'.

New in version v2.1: The pages, language and reading_order keyword arguments and support for image/bmp content
begin_recognize_content_from_url

Extract text and layout information from a given document. The input document must be the location (URL) of the document to be analyzed.

New in version v2.1: The pages, language and reading_order keyword arguments and support for image/bmp content
begin_recognize_custom_forms

Analyze a custom form with a model trained with or without labels. The form to analyze should be of the same type as the forms that were used to train the model. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff', or 'image/bmp'.
begin_recognize_custom_forms_from_url

Analyze a custom form with a model trained with or without labels. The form to analyze should be of the same type as the forms that were used to train the model. The input document must be the location (URL) of the document to be analyzed.
begin_recognize_identity_documents

Extract field text and semantic values from a given identity document. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff' or 'image/bmp'.

See fields found on an identity document here: https://aka.ms/formrecognizer/iddocumentfields

New in version v2.1: The begin_recognize_identity_documents client method
begin_recognize_identity_documents_from_url

Extract field text and semantic values from a given identity document. The input document must be the location (URL) of the identity document to be analyzed.

See fields found on an identity document here: https://aka.ms/formrecognizer/iddocumentfields

New in version v2.1: The begin_recognize_identity_documents_from_url client method
begin_recognize_invoices

Extract field text and semantic values from a given invoice. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff' or 'image/bmp'.

See fields found on a invoice here: https://aka.ms/formrecognizer/invoicefields

New in version v2.1: The begin_recognize_invoices client method
begin_recognize_invoices_from_url

Extract field text and semantic values from a given invoice. The input document must be the location (URL) of the invoice to be analyzed.

See fields found on a invoice card here: https://aka.ms/formrecognizer/invoicefields

New in version v2.1: The begin_recognize_invoices_from_url client method
begin_recognize_receipts

Extract field text and semantic values from a given sales receipt. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff' or 'image/bmp'.

See fields found on a receipt here: https://aka.ms/formrecognizer/receiptfields

New in version v2.1: The locale and pages keyword arguments and support for image/bmp content
begin_recognize_receipts_from_url

Extract field text and semantic values from a given sales receipt. The input document must be the location (URL) of the receipt to be analyzed.

See fields found on a receipt here: https://aka.ms/formrecognizer/receiptfields

New in version v2.1: The locale and pages keyword arguments and support for image/bmp content
close

Close the FormRecognizerClient session.
send_request

Runs a network request using the client's existing pipeline.

The request URL can be relative to the base URL. The service API version used for the request is the same as the client's unless otherwise specified. Overriding the client's configured API version in relative URL is supported on client with API version 2022-08-31 and later. Overriding in absolute URL supported on client with any API version. This method does not raise if the response is an error; to raise an exception, call raise_for_status() on the returned response object. For more information about how to send custom requests with this method, see https://aka.ms/azsdk/dpcodegen/python/send_request.

begin_recognize_business_cards

Extract field text and semantic values from a given business card. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff' or 'image/bmp'.

See fields found on a business card here: https://aka.ms/formrecognizer/businesscardfields

New in version v2.1: The begin_recognize_business_cards client method

begin_recognize_business_cards(business_card: bytes | IO[bytes], **kwargs: Any) -> LROPoller[List[RecognizedForm]]

Parameters

Name Description
business_card
Required
bytes or IO[bytes]

JPEG, PNG, PDF, TIFF, or BMP type file stream or bytes.

Keyword-Only Parameters

Name Description
locale
str

Locale of the business card. Supported locales include: en-US, en-AU, en-CA, en-GB, and en-IN.
include_field_elements
bool

Whether or not to include all lines per page and field elements such as lines, words, and selection marks for each form field.
pages
list[str]

Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=["1-3", "5-6"]. Separate each page number or range with a comma.
content_type
str or FormContentType

Content-type of the body sent to the API. Content-type is auto-detected, but can be overridden by passing this keyword argument. For options, see FormContentType.
continuation_token
str

A continuation token to restart a poller from a saved state.

Returns

Type Description
LROPoller[list[RecognizedForm]]

An instance of an LROPoller. Call result() on the poller object to return a list[RecognizedForm].

Exceptions

Type Description
HttpResponseError

Examples

Recognize business cards from a file.


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

   endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
   key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]

   form_recognizer_client = FormRecognizerClient(
       endpoint=endpoint, credential=AzureKeyCredential(key)
   )
   with open(path_to_sample_forms, "rb") as f:
       poller = form_recognizer_client.begin_recognize_business_cards(business_card=f, locale="en-US")
   business_cards = poller.result()

   for idx, business_card in enumerate(business_cards):
       print("--------Recognizing business card #{}--------".format(idx+1))
       contact_names = business_card.fields.get("ContactNames")
       if contact_names:
           for contact_name in contact_names.value:
               print("Contact First Name: {} has confidence: {}".format(
                   contact_name.value["FirstName"].value, contact_name.value["FirstName"].confidence
               ))
               print("Contact Last Name: {} has confidence: {}".format(
                   contact_name.value["LastName"].value, contact_name.value["LastName"].confidence
               ))
       company_names = business_card.fields.get("CompanyNames")
       if company_names:
           for company_name in company_names.value:
               print("Company Name: {} has confidence: {}".format(company_name.value, company_name.confidence))
       departments = business_card.fields.get("Departments")
       if departments:
           for department in departments.value:
               print("Department: {} has confidence: {}".format(department.value, department.confidence))
       job_titles = business_card.fields.get("JobTitles")
       if job_titles:
           for job_title in job_titles.value:
               print("Job Title: {} has confidence: {}".format(job_title.value, job_title.confidence))
       emails = business_card.fields.get("Emails")
       if emails:
           for email in emails.value:
               print("Email: {} has confidence: {}".format(email.value, email.confidence))
       websites = business_card.fields.get("Websites")
       if websites:
           for website in websites.value:
               print("Website: {} has confidence: {}".format(website.value, website.confidence))
       addresses = business_card.fields.get("Addresses")
       if addresses:
           for address in addresses.value:
               print("Address: {} has confidence: {}".format(address.value, address.confidence))
       mobile_phones = business_card.fields.get("MobilePhones")
       if mobile_phones:
           for phone in mobile_phones.value:
               print("Mobile phone number: {} has confidence: {}".format(phone.value, phone.confidence))
       faxes = business_card.fields.get("Faxes")
       if faxes:
           for fax in faxes.value:
               print("Fax number: {} has confidence: {}".format(fax.value, fax.confidence))
       work_phones = business_card.fields.get("WorkPhones")
       if work_phones:
           for work_phone in work_phones.value:
               print("Work phone number: {} has confidence: {}".format(work_phone.value, work_phone.confidence))
       other_phones = business_card.fields.get("OtherPhones")
       if other_phones:
           for other_phone in other_phones.value:
               print("Other phone number: {} has confidence: {}".format(other_phone.value, other_phone.confidence))

begin_recognize_business_cards_from_url

Extract field text and semantic values from a given business card. The input document must be the location (URL) of the card to be analyzed.

See fields found on a business card here: https://aka.ms/formrecognizer/businesscardfields

New in version v2.1: The begin_recognize_business_cards_from_url client method

begin_recognize_business_cards_from_url(business_card_url: str, **kwargs: Any) -> LROPoller[List[RecognizedForm]]

Parameters

Name Description
business_card_url
Required
str

The URL of the business card to analyze. The input must be a valid, encoded URL of one of the supported formats: JPEG, PNG, PDF, TIFF, or BMP.

Keyword-Only Parameters

Name Description
locale
str

Locale of the business card. Supported locales include: en-US, en-AU, en-CA, en-GB, and en-IN.
include_field_elements
bool

Whether or not to include all lines per page and field elements such as lines, words, and selection marks for each form field.
pages
list[str]

Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=["1-3", "5-6"]. Separate each page number or range with a comma.
continuation_token
str

A continuation token to restart a poller from a saved state.

Returns

Type Description
LROPoller[list[RecognizedForm]]

An instance of an LROPoller. Call result() on the poller object to return a list[RecognizedForm].

Exceptions

Type Description
HttpResponseError

begin_recognize_content

Extract text and content/layout information from a given document. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff' or 'image/bmp'.

New in version v2.1: The pages, language and reading_order keyword arguments and support for image/bmp content

begin_recognize_content(form: bytes | IO[bytes], **kwargs: Any) -> LROPoller[List[FormPage]]

Parameters

Name Description
form
Required
bytes or IO[bytes]

JPEG, PNG, PDF, TIFF, or BMP type file stream or bytes.

Keyword-Only Parameters

Name Description
pages
list[str]

Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=["1-3", "5-6"]. Separate each page number or range with a comma.
language
str

The BCP-47 language code of the text in the document. See supported language codes here: https://docs.microsoft.com/azure/cognitive-services/form-recognizer/language-support. Content supports auto language identification and multilanguage documents, so only provide a language code if you would like to force the documented to be processed as that specific language.
reading_order
str

Reading order algorithm to sort the text lines returned. Supported reading orders include: basic (default), natural. Set 'basic' to sort lines left to right and top to bottom, although in some cases proximity is treated with higher priority. Set 'natural' to sort lines by using positional information to keep nearby lines together.
content_type
str or FormContentType

Content-type of the body sent to the API. Content-type is auto-detected, but can be overridden by passing this keyword argument. For options, see FormContentType.
continuation_token
str

A continuation token to restart a poller from a saved state.

Returns

Type Description
LROPoller[list[FormPage]]

An instance of an LROPoller. Call result() on the poller object to return a list[FormPage].

Exceptions

Type Description
HttpResponseError

Examples

Recognize text and content/layout information from a form.


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

   endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
   key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]

   form_recognizer_client = FormRecognizerClient(endpoint=endpoint, credential=AzureKeyCredential(key))
   with open(path_to_sample_forms, "rb") as f:
       poller = form_recognizer_client.begin_recognize_content(form=f)
   form_pages = poller.result()

   for idx, content in enumerate(form_pages):
       print("----Recognizing content from page #{}----".format(idx+1))
       print("Page has width: {} and height: {}, measured with unit: {}".format(
           content.width,
           content.height,
           content.unit
       ))
       for table_idx, table in enumerate(content.tables):
           print("Table # {} has {} rows and {} columns".format(table_idx, table.row_count, table.column_count))
           print("Table # {} location on page: {}".format(table_idx, format_bounding_box(table.bounding_box)))
           for cell in table.cells:
               print("...Cell[{}][{}] has text '{}' within bounding box '{}'".format(
                   cell.row_index,
                   cell.column_index,
                   cell.text,
                   format_bounding_box(cell.bounding_box)
               ))

       for line_idx, line in enumerate(content.lines):
           print("Line # {} has word count '{}' and text '{}' within bounding box '{}'".format(
               line_idx,
               len(line.words),
               line.text,
               format_bounding_box(line.bounding_box)
           ))
           if line.appearance:
               if line.appearance.style_name == "handwriting" and line.appearance.style_confidence > 0.8:
                   print("Text line '{}' is handwritten and might be a signature.".format(line.text))
           for word in line.words:
               print("...Word '{}' has a confidence of {}".format(word.text, word.confidence))

       for selection_mark in content.selection_marks:
           print("Selection mark is '{}' within bounding box '{}' and has a confidence of {}".format(
               selection_mark.state,
               format_bounding_box(selection_mark.bounding_box),
               selection_mark.confidence
           ))
       print("----------------------------------------")

begin_recognize_content_from_url

Extract text and layout information from a given document. The input document must be the location (URL) of the document to be analyzed.

New in version v2.1: The pages, language and reading_order keyword arguments and support for image/bmp content

begin_recognize_content_from_url(form_url: str, **kwargs: Any) -> LROPoller[List[FormPage]]

Parameters

Name Description
form_url
Required
str

The URL of the form to analyze. The input must be a valid, encoded URL of one of the supported formats: JPEG, PNG, PDF, TIFF, or BMP.

Keyword-Only Parameters

Name Description
pages
list[str]

Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=["1-3", "5-6"]. Separate each page number or range with a comma.
language
str

The BCP-47 language code of the text in the document. See supported language codes here: https://docs.microsoft.com/azure/cognitive-services/form-recognizer/language-support. Content supports auto language identification and multilanguage documents, so only provide a language code if you would like to force the documented to be processed as that specific language.
reading_order
str

Reading order algorithm to sort the text lines returned. Supported reading orders include: basic (default), natural. Set 'basic' to sort lines left to right and top to bottom, although in some cases proximity is treated with higher priority. Set 'natural' to sort lines by using positional information to keep nearby lines together.
continuation_token
str

A continuation token to restart a poller from a saved state.

Returns

Type Description
LROPoller[list[FormPage]]

An instance of an LROPoller. Call result() on the poller object to return a list[FormPage].

Exceptions

Type Description
HttpResponseError

begin_recognize_custom_forms

Analyze a custom form with a model trained with or without labels. The form to analyze should be of the same type as the forms that were used to train the model. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff', or 'image/bmp'.

begin_recognize_custom_forms(model_id: str, form: bytes | IO[bytes], **kwargs: Any) -> LROPoller[List[RecognizedForm]]

Parameters

Name Description
model_id
Required
str

Custom model identifier.
form
Required
bytes or IO[bytes]

JPEG, PNG, PDF, TIFF, or BMP type file stream or bytes.

Keyword-Only Parameters

Name Description
include_field_elements
bool

Whether or not to include all lines per page and field elements such as lines, words, and selection marks for each form field.
content_type
str or FormContentType

Content-type of the body sent to the API. Content-type is auto-detected, but can be overridden by passing this keyword argument. For options, see FormContentType.
pages
list[str]

Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=["1-3", "5-6"]. Separate each page number or range with a comma.
continuation_token
str

A continuation token to restart a poller from a saved state.

Returns

Type Description
LROPoller[list[RecognizedForm]]

An instance of an LROPoller. Call result() on the poller object to return a list[RecognizedForm].

Exceptions

Type Description
HttpResponseError

Examples

Recognize fields and values from a custom form.


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

   endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
   key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]
   model_id = os.getenv("CUSTOM_TRAINED_MODEL_ID", custom_model_id)

   form_recognizer_client = FormRecognizerClient(
       endpoint=endpoint, credential=AzureKeyCredential(key)
   )

   # Make sure your form's type is included in the list of form types the custom model can recognize
   with open(path_to_sample_forms, "rb") as f:
       poller = form_recognizer_client.begin_recognize_custom_forms(
           model_id=model_id, form=f, include_field_elements=True
       )
   forms = poller.result()

   for idx, form in enumerate(forms):
       print("--------Recognizing Form #{}--------".format(idx+1))
       print("Form has type {}".format(form.form_type))
       print("Form has form type confidence {}".format(form.form_type_confidence))
       print("Form was analyzed with model with ID {}".format(form.model_id))
       for name, field in form.fields.items():
           # each field is of type FormField
           # label_data is populated if you are using a model trained without labels,
           # since the service needs to make predictions for labels if not explicitly given to it.
           if field.label_data:
               print("...Field '{}' has label '{}' with a confidence score of {}".format(
                   name,
                   field.label_data.text,
                   field.confidence
               ))

           print("...Label '{}' has value '{}' with a confidence score of {}".format(
               field.label_data.text if field.label_data else name, field.value, field.confidence
           ))

       # iterate over tables, lines, and selection marks on each page
       for page in form.pages:
           for i, table in enumerate(page.tables):
               print("\nTable {} on page {}".format(i+1, table.page_number))
               for cell in table.cells:
                   print("...Cell[{}][{}] has text '{}' with confidence {}".format(
                       cell.row_index, cell.column_index, cell.text, cell.confidence
                   ))
           print("\nLines found on page {}".format(page.page_number))
           for line in page.lines:
               print("...Line '{}' is made up of the following words: ".format(line.text))
               for word in line.words:
                   print("......Word '{}' has a confidence of {}".format(
                       word.text,
                       word.confidence
                   ))
           if page.selection_marks:
               print("\nSelection marks found on page {}".format(page.page_number))
               for selection_mark in page.selection_marks:
                   print("......Selection mark is '{}' and has a confidence of {}".format(
                       selection_mark.state,
                       selection_mark.confidence
                   ))

       print("-----------------------------------")

begin_recognize_custom_forms_from_url

Analyze a custom form with a model trained with or without labels. The form to analyze should be of the same type as the forms that were used to train the model. The input document must be the location (URL) of the document to be analyzed.

begin_recognize_custom_forms_from_url(model_id: str, form_url: str, **kwargs: Any) -> LROPoller[List[RecognizedForm]]

Parameters

Name Description
model_id
Required
str

Custom model identifier.
form_url
Required
str

The URL of the form to analyze. The input must be a valid, encoded URL of one of the supported formats: JPEG, PNG, PDF, TIFF, or BMP.

Keyword-Only Parameters

Name Description
include_field_elements
bool

Whether or not to include all lines per page and field elements such as lines, words, and selection marks for each form field.
pages
list[str]

Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=["1-3", "5-6"]. Separate each page number or range with a comma.
continuation_token
str

A continuation token to restart a poller from a saved state.

Returns

Type Description
LROPoller[list[RecognizedForm]]

An instance of an LROPoller. Call result() on the poller object to return a list[RecognizedForm].

Exceptions

Type Description
HttpResponseError

begin_recognize_identity_documents

Extract field text and semantic values from a given identity document. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff' or 'image/bmp'.

See fields found on an identity document here: https://aka.ms/formrecognizer/iddocumentfields

New in version v2.1: The begin_recognize_identity_documents client method

begin_recognize_identity_documents(identity_document: bytes | IO[bytes], **kwargs: Any) -> LROPoller[List[RecognizedForm]]

Parameters

Name Description
identity_document
Required
bytes or IO[bytes]

JPEG, PNG, PDF, TIFF, or BMP type file stream or bytes.

Keyword-Only Parameters

Name Description
include_field_elements
bool

Whether or not to include all lines per page and field elements such as lines, words, and selection marks for each form field.
content_type
str or FormContentType

Content-type of the body sent to the API. Content-type is auto-detected, but can be overridden by passing this keyword argument. For options, see FormContentType.
continuation_token
str

A continuation token to restart a poller from a saved state.
pages
list[str]

Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=["1-3", "5-6"]. Separate each page number or range with a comma.

Returns

Type Description
LROPoller[list[RecognizedForm]]

An instance of an LROPoller. Call result() on the poller object to return a list[RecognizedForm].

Exceptions

Type Description
HttpResponseError

Examples

Recognize identity document fields.


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

   endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
   key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]

   form_recognizer_client = FormRecognizerClient(
       endpoint=endpoint, credential=AzureKeyCredential(key)
   )
   with open(path_to_sample_forms, "rb") as f:
       poller = form_recognizer_client.begin_recognize_identity_documents(identity_document=f)
   id_documents = poller.result()

   for idx, id_document in enumerate(id_documents):
       print("--------Recognizing ID document #{}--------".format(idx+1))
       first_name = id_document.fields.get("FirstName")
       if first_name:
           print("First Name: {} has confidence: {}".format(first_name.value, first_name.confidence))
       last_name = id_document.fields.get("LastName")
       if last_name:
           print("Last Name: {} has confidence: {}".format(last_name.value, last_name.confidence))
       document_number = id_document.fields.get("DocumentNumber")
       if document_number:
           print("Document Number: {} has confidence: {}".format(document_number.value, document_number.confidence))
       dob = id_document.fields.get("DateOfBirth")
       if dob:
           print("Date of Birth: {} has confidence: {}".format(dob.value, dob.confidence))
       doe = id_document.fields.get("DateOfExpiration")
       if doe:
           print("Date of Expiration: {} has confidence: {}".format(doe.value, doe.confidence))
       sex = id_document.fields.get("Sex")
       if sex:
           print("Sex: {} has confidence: {}".format(sex.value, sex.confidence))
       address = id_document.fields.get("Address")
       if address:
           print("Address: {} has confidence: {}".format(address.value, address.confidence))
       country_region = id_document.fields.get("CountryRegion")
       if country_region:
           print("Country/Region: {} has confidence: {}".format(country_region.value, country_region.confidence))
       region = id_document.fields.get("Region")
       if region:
           print("Region: {} has confidence: {}".format(region.value, region.confidence))

begin_recognize_identity_documents_from_url

Extract field text and semantic values from a given identity document. The input document must be the location (URL) of the identity document to be analyzed.

See fields found on an identity document here: https://aka.ms/formrecognizer/iddocumentfields

New in version v2.1: The begin_recognize_identity_documents_from_url client method

begin_recognize_identity_documents_from_url(identity_document_url: str, **kwargs: Any) -> LROPoller[List[RecognizedForm]]

Parameters

Name Description
identity_document_url
Required
str

The URL of the identity document to analyze. The input must be a valid, encoded URL of one of the supported formats: JPEG, PNG, PDF, TIFF, or BMP.

Keyword-Only Parameters

Name Description
include_field_elements
bool

Whether or not to include all lines per page and field elements such as lines, words, and selection marks for each form field.
continuation_token
str

A continuation token to restart a poller from a saved state.
pages
list[str]

Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=["1-3", "5-6"]. Separate each page number or range with a comma.

Returns

Type Description
LROPoller[list[RecognizedForm]]

An instance of an LROPoller. Call result() on the poller object to return a list[RecognizedForm].

Exceptions

Type Description
HttpResponseError

begin_recognize_invoices

Extract field text and semantic values from a given invoice. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff' or 'image/bmp'.

See fields found on a invoice here: https://aka.ms/formrecognizer/invoicefields

New in version v2.1: The begin_recognize_invoices client method

begin_recognize_invoices(invoice: bytes | IO[bytes], **kwargs: Any) -> LROPoller[List[RecognizedForm]]

Parameters

Name Description
invoice
Required
bytes or IO[bytes]

JPEG, PNG, PDF, TIFF, or BMP type file stream or bytes.

Keyword-Only Parameters

Name Description
locale
str

Locale of the invoice. Supported locales include: en-US
include_field_elements
bool

Whether or not to include all lines per page and field elements such as lines, words, and selection marks for each form field.
pages
list[str]

Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=["1-3", "5-6"]. Separate each page number or range with a comma.
content_type
str or FormContentType

Content-type of the body sent to the API. Content-type is auto-detected, but can be overridden by passing this keyword argument. For options, see FormContentType.
continuation_token
str

A continuation token to restart a poller from a saved state.

Returns

Type Description
LROPoller[list[RecognizedForm]]

An instance of an LROPoller. Call result() on the poller object to return a list[RecognizedForm].

Exceptions

Type Description
HttpResponseError

Examples

Recognize invoices from a file.


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

   endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
   key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]

   form_recognizer_client = FormRecognizerClient(
       endpoint=endpoint, credential=AzureKeyCredential(key)
   )
   with open(path_to_sample_forms, "rb") as f:
       poller = form_recognizer_client.begin_recognize_invoices(invoice=f, locale="en-US")
   invoices = poller.result()

   for idx, invoice in enumerate(invoices):
       print("--------Recognizing invoice #{}--------".format(idx+1))
       vendor_name = invoice.fields.get("VendorName")
       if vendor_name:
           print("Vendor Name: {} has confidence: {}".format(vendor_name.value, vendor_name.confidence))
       vendor_address = invoice.fields.get("VendorAddress")
       if vendor_address:
           print("Vendor Address: {} has confidence: {}".format(vendor_address.value, vendor_address.confidence))
       vendor_address_recipient = invoice.fields.get("VendorAddressRecipient")
       if vendor_address_recipient:
           print("Vendor Address Recipient: {} has confidence: {}".format(vendor_address_recipient.value, vendor_address_recipient.confidence))
       customer_name = invoice.fields.get("CustomerName")
       if customer_name:
           print("Customer Name: {} has confidence: {}".format(customer_name.value, customer_name.confidence))
       customer_id = invoice.fields.get("CustomerId")
       if customer_id:
           print("Customer Id: {} has confidence: {}".format(customer_id.value, customer_id.confidence))
       customer_address = invoice.fields.get("CustomerAddress")
       if customer_address:
           print("Customer Address: {} has confidence: {}".format(customer_address.value, customer_address.confidence))
       customer_address_recipient = invoice.fields.get("CustomerAddressRecipient")
       if customer_address_recipient:
           print("Customer Address Recipient: {} has confidence: {}".format(customer_address_recipient.value, customer_address_recipient.confidence))
       invoice_id = invoice.fields.get("InvoiceId")
       if invoice_id:
           print("Invoice Id: {} has confidence: {}".format(invoice_id.value, invoice_id.confidence))
       invoice_date = invoice.fields.get("InvoiceDate")
       if invoice_date:
           print("Invoice Date: {} has confidence: {}".format(invoice_date.value, invoice_date.confidence))
       invoice_total = invoice.fields.get("InvoiceTotal")
       if invoice_total:
           print("Invoice Total: {} has confidence: {}".format(invoice_total.value, invoice_total.confidence))
       due_date = invoice.fields.get("DueDate")
       if due_date:
           print("Due Date: {} has confidence: {}".format(due_date.value, due_date.confidence))
       purchase_order = invoice.fields.get("PurchaseOrder")
       if purchase_order:
           print("Purchase Order: {} has confidence: {}".format(purchase_order.value, purchase_order.confidence))
       billing_address = invoice.fields.get("BillingAddress")
       if billing_address:
           print("Billing Address: {} has confidence: {}".format(billing_address.value, billing_address.confidence))
       billing_address_recipient = invoice.fields.get("BillingAddressRecipient")
       if billing_address_recipient:
           print("Billing Address Recipient: {} has confidence: {}".format(billing_address_recipient.value, billing_address_recipient.confidence))
       shipping_address = invoice.fields.get("ShippingAddress")
       if shipping_address:
           print("Shipping Address: {} has confidence: {}".format(shipping_address.value, shipping_address.confidence))
       shipping_address_recipient = invoice.fields.get("ShippingAddressRecipient")
       if shipping_address_recipient:
           print("Shipping Address Recipient: {} has confidence: {}".format(shipping_address_recipient.value, shipping_address_recipient.confidence))
       print("Invoice items:")
       for idx, item in enumerate(invoice.fields.get("Items").value):
           print("...Item #{}".format(idx+1))
           item_description = item.value.get("Description")
           if item_description:
               print("......Description: {} has confidence: {}".format(item_description.value, item_description.confidence))
           item_quantity = item.value.get("Quantity")
           if item_quantity:
               print("......Quantity: {} has confidence: {}".format(item_quantity.value, item_quantity.confidence))
           unit = item.value.get("Unit")
           if unit:
               print("......Unit: {} has confidence: {}".format(unit.value, unit.confidence))
           unit_price = item.value.get("UnitPrice")
           if unit_price:
               print("......Unit Price: {} has confidence: {}".format(unit_price.value, unit_price.confidence))
           product_code = item.value.get("ProductCode")
           if product_code:
               print("......Product Code: {} has confidence: {}".format(product_code.value, product_code.confidence))
           item_date = item.value.get("Date")
           if item_date:
               print("......Date: {} has confidence: {}".format(item_date.value, item_date.confidence))
           tax = item.value.get("Tax")
           if tax:
               print("......Tax: {} has confidence: {}".format(tax.value, tax.confidence))
           amount = item.value.get("Amount")
           if amount:
               print("......Amount: {} has confidence: {}".format(amount.value, amount.confidence))
       subtotal = invoice.fields.get("SubTotal")
       if subtotal:
           print("Subtotal: {} has confidence: {}".format(subtotal.value, subtotal.confidence))
       total_tax = invoice.fields.get("TotalTax")
       if total_tax:
           print("Total Tax: {} has confidence: {}".format(total_tax.value, total_tax.confidence))
       previous_unpaid_balance = invoice.fields.get("PreviousUnpaidBalance")
       if previous_unpaid_balance:
           print("Previous Unpaid Balance: {} has confidence: {}".format(previous_unpaid_balance.value, previous_unpaid_balance.confidence))
       amount_due = invoice.fields.get("AmountDue")
       if amount_due:
           print("Amount Due: {} has confidence: {}".format(amount_due.value, amount_due.confidence))
       service_start_date = invoice.fields.get("ServiceStartDate")
       if service_start_date:
           print("Service Start Date: {} has confidence: {}".format(service_start_date.value, service_start_date.confidence))
       service_end_date = invoice.fields.get("ServiceEndDate")
       if service_end_date:
           print("Service End Date: {} has confidence: {}".format(service_end_date.value, service_end_date.confidence))
       service_address = invoice.fields.get("ServiceAddress")
       if service_address:
           print("Service Address: {} has confidence: {}".format(service_address.value, service_address.confidence))
       service_address_recipient = invoice.fields.get("ServiceAddressRecipient")
       if service_address_recipient:
           print("Service Address Recipient: {} has confidence: {}".format(service_address_recipient.value, service_address_recipient.confidence))
       remittance_address = invoice.fields.get("RemittanceAddress")
       if remittance_address:
           print("Remittance Address: {} has confidence: {}".format(remittance_address.value, remittance_address.confidence))
       remittance_address_recipient = invoice.fields.get("RemittanceAddressRecipient")
       if remittance_address_recipient:
           print("Remittance Address Recipient: {} has confidence: {}".format(remittance_address_recipient.value, remittance_address_recipient.confidence))

begin_recognize_invoices_from_url

Extract field text and semantic values from a given invoice. The input document must be the location (URL) of the invoice to be analyzed.

See fields found on a invoice card here: https://aka.ms/formrecognizer/invoicefields

New in version v2.1: The begin_recognize_invoices_from_url client method

begin_recognize_invoices_from_url(invoice_url: str, **kwargs: Any) -> LROPoller[List[RecognizedForm]]

Parameters

Name Description
invoice_url
Required
str

The URL of the invoice to analyze. The input must be a valid, encoded URL of one of the supported formats: JPEG, PNG, PDF, TIFF, or BMP.

Keyword-Only Parameters

Name Description
locale
str

Locale of the invoice. Supported locales include: en-US
include_field_elements
bool

Whether or not to include all lines per page and field elements such as lines, words, and selection marks for each form field.
pages
list[str]

Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=["1-3", "5-6"]. Separate each page number or range with a comma.
continuation_token
str

A continuation token to restart a poller from a saved state.

Returns

Type Description
LROPoller[list[RecognizedForm]]

An instance of an LROPoller. Call result() on the poller object to return a list[RecognizedForm].

Exceptions

Type Description
HttpResponseError

begin_recognize_receipts

Extract field text and semantic values from a given sales receipt. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff' or 'image/bmp'.

See fields found on a receipt here: https://aka.ms/formrecognizer/receiptfields

New in version v2.1: The locale and pages keyword arguments and support for image/bmp content

begin_recognize_receipts(receipt: bytes | IO[bytes], **kwargs: Any) -> LROPoller[List[RecognizedForm]]

Parameters

Name Description
receipt
Required
bytes or IO[bytes]

JPEG, PNG, PDF, TIFF, or BMP type file stream or bytes.

Keyword-Only Parameters

Name Description
include_field_elements
bool

Whether or not to include all lines per page and field elements such as lines, words, and selection marks for each form field.
content_type
str or FormContentType

Content-type of the body sent to the API. Content-type is auto-detected, but can be overridden by passing this keyword argument. For options, see FormContentType.
continuation_token
str

A continuation token to restart a poller from a saved state.
locale
str

Locale of the receipt. Supported locales include: en-US, en-AU, en-CA, en-GB, and en-IN.
pages
list[str]

Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=["1-3", "5-6"]. Separate each page number or range with a comma.

Returns

Type Description
LROPoller[list[RecognizedForm]]

An instance of an LROPoller. Call result() on the poller object to return a list[RecognizedForm].

Exceptions

Type Description
HttpResponseError

Examples

Recognize sales receipt fields.


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

   endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
   key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]

   form_recognizer_client = FormRecognizerClient(
       endpoint=endpoint, credential=AzureKeyCredential(key)
   )
   with open(path_to_sample_forms, "rb") as f:
       poller = form_recognizer_client.begin_recognize_receipts(receipt=f, locale="en-US")
   receipts = poller.result()

   for idx, receipt in enumerate(receipts):
       print("--------Recognizing receipt #{}--------".format(idx+1))
       receipt_type = receipt.fields.get("ReceiptType")
       if receipt_type:
           print("Receipt Type: {} has confidence: {}".format(receipt_type.value, receipt_type.confidence))
       merchant_name = receipt.fields.get("MerchantName")
       if merchant_name:
           print("Merchant Name: {} has confidence: {}".format(merchant_name.value, merchant_name.confidence))
       transaction_date = receipt.fields.get("TransactionDate")
       if transaction_date:
           print("Transaction Date: {} has confidence: {}".format(transaction_date.value, transaction_date.confidence))
       if receipt.fields.get("Items"):
           print("Receipt items:")
           for idx, item in enumerate(receipt.fields.get("Items").value):
               print("...Item #{}".format(idx+1))
               item_name = item.value.get("Name")
               if item_name:
                   print("......Item Name: {} has confidence: {}".format(item_name.value, item_name.confidence))
               item_quantity = item.value.get("Quantity")
               if item_quantity:
                   print("......Item Quantity: {} has confidence: {}".format(item_quantity.value, item_quantity.confidence))
               item_price = item.value.get("Price")
               if item_price:
                   print("......Individual Item Price: {} has confidence: {}".format(item_price.value, item_price.confidence))
               item_total_price = item.value.get("TotalPrice")
               if item_total_price:
                   print("......Total Item Price: {} has confidence: {}".format(item_total_price.value, item_total_price.confidence))
       subtotal = receipt.fields.get("Subtotal")
       if subtotal:
           print("Subtotal: {} has confidence: {}".format(subtotal.value, subtotal.confidence))
       tax = receipt.fields.get("Tax")
       if tax:
           print("Tax: {} has confidence: {}".format(tax.value, tax.confidence))
       tip = receipt.fields.get("Tip")
       if tip:
           print("Tip: {} has confidence: {}".format(tip.value, tip.confidence))
       total = receipt.fields.get("Total")
       if total:
           print("Total: {} has confidence: {}".format(total.value, total.confidence))
       print("--------------------------------------")

begin_recognize_receipts_from_url

Extract field text and semantic values from a given sales receipt. The input document must be the location (URL) of the receipt to be analyzed.

See fields found on a receipt here: https://aka.ms/formrecognizer/receiptfields

New in version v2.1: The locale and pages keyword arguments and support for image/bmp content

begin_recognize_receipts_from_url(receipt_url: str, **kwargs: Any) -> LROPoller[List[RecognizedForm]]

Parameters

Name Description
receipt_url
Required
str

The URL of the receipt to analyze. The input must be a valid, encoded URL of one of the supported formats: JPEG, PNG, PDF, TIFF, or BMP.

Keyword-Only Parameters

Name Description
include_field_elements
bool

Whether or not to include all lines per page and field elements such as lines, words, and selection marks for each form field.
continuation_token
str

A continuation token to restart a poller from a saved state.
locale
str

Locale of the receipt. Supported locales include: en-US, en-AU, en-CA, en-GB, and en-IN.
pages
list[str]

Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=["1-3", "5-6"]. Separate each page number or range with a comma.

Returns

Type Description
LROPoller[list[RecognizedForm]]

An instance of an LROPoller. Call result() on the poller object to return a list[RecognizedForm].

Exceptions

Type Description
HttpResponseError

Examples

Recognize sales receipt fields from a URL.


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

   endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
   key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]

   form_recognizer_client = FormRecognizerClient(
       endpoint=endpoint, credential=AzureKeyCredential(key)
   )
   url = "https://raw.githubusercontent.com/Azure/azure-sdk-for-python/main/sdk/formrecognizer/azure-ai-formrecognizer/tests/sample_forms/receipt/contoso-receipt.png"
   poller = form_recognizer_client.begin_recognize_receipts_from_url(receipt_url=url)
   receipts = poller.result()

   for idx, receipt in enumerate(receipts):
       print("--------Recognizing receipt #{}--------".format(idx+1))
       receipt_type = receipt.fields.get("ReceiptType")
       if receipt_type:
           print("Receipt Type: {} has confidence: {}".format(receipt_type.value, receipt_type.confidence))
       merchant_name = receipt.fields.get("MerchantName")
       if merchant_name:
           print("Merchant Name: {} has confidence: {}".format(merchant_name.value, merchant_name.confidence))
       transaction_date = receipt.fields.get("TransactionDate")
       if transaction_date:
           print("Transaction Date: {} has confidence: {}".format(transaction_date.value, transaction_date.confidence))
       if receipt.fields.get("Items"):
           print("Receipt items:")
           for idx, item in enumerate(receipt.fields.get("Items").value):
               print("...Item #{}".format(idx+1))
               item_name = item.value.get("Name")
               if item_name:
                   print("......Item Name: {} has confidence: {}".format(item_name.value, item_name.confidence))
               item_quantity = item.value.get("Quantity")
               if item_quantity:
                   print("......Item Quantity: {} has confidence: {}".format(item_quantity.value, item_quantity.confidence))
               item_price = item.value.get("Price")
               if item_price:
                   print("......Individual Item Price: {} has confidence: {}".format(item_price.value, item_price.confidence))
               item_total_price = item.value.get("TotalPrice")
               if item_total_price:
                   print("......Total Item Price: {} has confidence: {}".format(item_total_price.value, item_total_price.confidence))
       subtotal = receipt.fields.get("Subtotal")
       if subtotal:
           print("Subtotal: {} has confidence: {}".format(subtotal.value, subtotal.confidence))
       tax = receipt.fields.get("Tax")
       if tax:
           print("Tax: {} has confidence: {}".format(tax.value, tax.confidence))
       tip = receipt.fields.get("Tip")
       if tip:
           print("Tip: {} has confidence: {}".format(tip.value, tip.confidence))
       total = receipt.fields.get("Total")
       if total:
           print("Total: {} has confidence: {}".format(total.value, total.confidence))
       print("--------------------------------------")

close

Close the FormRecognizerClient session.

close() -> None

Keyword-Only Parameters

Name Description
locale
str

Locale of the business card. Supported locales include: en-US, en-AU, en-CA, en-GB, and en-IN.
include_field_elements
bool

Whether or not to include all lines per page and field elements such as lines, words, and selection marks for each form field.
pages
list[str]

Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like pages=["1-3", "5-6"]. Separate each page number or range with a comma.
content_type
str or FormContentType

Content-type of the body sent to the API. Content-type is auto-detected, but can be overridden by passing this keyword argument. For options, see FormContentType.
continuation_token
str

A continuation token to restart a poller from a saved state.

Exceptions

Type Description
HttpResponseError

send_request

Runs a network request using the client's existing pipeline.

The request URL can be relative to the base URL. The service API version used for the request is the same as the client's unless otherwise specified. Overriding the client's configured API version in relative URL is supported on client with API version 2022-08-31 and later. Overriding in absolute URL supported on client with any API version. This method does not raise if the response is an error; to raise an exception, call raise_for_status() on the returned response object. For more information about how to send custom requests with this method, see https://aka.ms/azsdk/dpcodegen/python/send_request.

send_request(request: HttpRequest, *, stream: bool = False, **kwargs) -> HttpResponse

Parameters

Name Description
request
Required
HttpRequest

The network request you want to make.

Keyword-Only Parameters

Name Description
stream
bool

Whether the response payload will be streamed. Defaults to False.

Returns

Type Description
HttpResponse

The response of your network call. Does not do error handling on your response.

Exceptions

Type Description
HttpResponseError