<Microsoft> developer portal

Form Recognizer 2022-08-31

Form Recognizer extracts information from forms and images into structured data. It includes the following options:

Read - Extract text from documents.
Layout - Extract text and layout information from documents.
Document - Extract text, layout, entities, and general key-value pairs from documents.
Business Card - Extract key information from business cards.
ID Document - Extract key information from passports and ID cards.
Invoice - Extract key information from invoices.
Receipt - Extract key information from receipts.
US W2 Tax - Extract key information from IRS US W2 tax forms (year 2018-2021).
Vaccination Card - Extract key information from US Covid-19 CDC vaccination cards.
Health Insurance Card - Extract key information from US health insurance cards.
Custom - Extracts information from forms (PDFs and images) into structured data based on a model created from a set of representative training forms. Form Recognizer learns the structure of your forms to intelligently extract text and data. It ingests text from forms, applies machine learning technology to identify keys, tables, and fields, and then outputs structured data that includes the relationships within the original file.

Analyze - Get analyze result

Gets the result of document analysis.

Select the testing console in the region where you created your resource:

Open API testing console

Request URL

https://{endpoint}/formrecognizer/documentModels/{modelId}/analyzeResults/{resultId}?api-version=2022-08-31

Request parameters

modelId

string

Format - [a-zA-Z0-9][a-zA-Z0-9._~-]{1,63}. Unique model name.

resultId

string

Analyze operation result ID.

Request headers

Ocp-Apim-Subscription-Key

string

Subscription key which provides access to this API. Found in your Cognitive Services accounts.

Request body

Response 200

Supported Document Fields

businessCard

Field	Type	Description	Example
ContactNames	array
ContactNames.*	object	Contact name	Chris Smith
ContactNames.*.FirstName	string	First (given) name of contact	Chris
ContactNames.*.LastName	string	Last (family) name of contact	Smith
CompanyNames	array
CompanyNames.*	string	Company name	CONTOSO
JobTitles	array
JobTitles.*	string	Job title	Senior Researcher
Departments	array
Departments.*	string	Department or organization	Cloud & AI Department
Addresses	array
Addresses.*	address	Address	4001 1st Ave NE Redmond, WA 98052
WorkPhones	array
WorkPhones.*	phoneNumber	Work phone number	+1 (987) 213-5674
MobilePhones	array
MobilePhones.*	phoneNumber	Mobile phone number	+1 (987) 123-4567
Faxes	array
Faxes.*	phoneNumber	Fax number	+1 (987) 312-6745
OtherPhones	array
OtherPhones.*	phoneNumber	Other phone number	+1 (987) 213-5673
Emails	array
Emails.*	string	Contact email	chris.smith@contoso.com
Websites	array
Websites.*	string	Website	https://www.contoso.com

idDocument.driverLicense

Field	Type	Description	Example
CountryRegion	countryRegion	Country or region code	USA
Region	string	State or province	Washington
DocumentNumber	string	Driver license number	WDLABCD456DG
DocumentDiscriminator	string	Driver license document discriminator	12645646464554646456464544
FirstName	string	Given name and middle initial if applicable	LIAM R.
LastName	string	Surname	TALBOT
Address	address	Address	123 STREET ADDRESS YOUR CITY WA 99999-1234
DateOfBirth	date	Date of birth	01/06/1958
DateOfExpiration	date	Date of expiration	08/12/2020
DateOfIssue	date	Date of issue	08/12/2012
EyeColor	string	Eye color	BLU
HairColor	string	Hair color	BRO
Height	string	Height	5'11"
Weight	string	Weight	185LB
Sex	string	Sex	M
Endorsements	string	Endorsements	L
Restrictions	string	Restrictions	B
VehicleClassifications	string	Vehicle classification	D

idDocument.passport

Field	Type	Description	Example
DocumentNumber	string	Passport number	340020013
FirstName	string	Given name and middle initial if applicable	JENNIFER
MiddleName	string	Name between given name and surname	REYES
LastName	string	Surname	BROOKS
Aliases	array
Aliases.*	string	Also known as	MAY LIN
DateOfBirth	date	Date of birth	1980-01-01
DateOfExpiration	date	Date of expiration	2019-05-05
DateOfIssue	date	Date of issue	2014-05-06
Sex	string	Sex	F
CountryRegion	countryRegion	Issuing country or organization	USA
DocumentType	string	Document type	P
Nationality	countryRegion	Nationality	USA
PlaceOfBirth	string	Place of birth	MASSACHUSETTS, U.S.A.
PlaceOfIssue	string	Place of issue	LA PAZ
IssuingAuthority	string	Issuing authority	United States Department of State
PersonalNumber	string	Personal Id. No.	A234567893
MachineReadableZone	object	Machine readable zone (MRZ)	P<USABROOKS<<JENNIFER<<<<<<<<<<<<<<<<<<<<<<< 3400200135USA8001014F1905054710000307<715816
MachineReadableZone.FirstName	string	Given name and middle initial if applicable	JENNIFER
MachineReadableZone.LastName	string	Surname	BROOKS
MachineReadableZone.DocumentNumber	string	Passport number	340020013
MachineReadableZone.CountryRegion	countryRegion	Issuing country or organization	USA
MachineReadableZone.Nationality	countryRegion	Nationality	USA
MachineReadableZone.DateOfBirth	date	Date of birth	1980-01-01
MachineReadableZone.DateOfExpiration	date	Date of expiration	2019-05-05
MachineReadableZone.Sex	string	Sex	F

idDocument.nationalIdentityCard

Field	Type	Description	Example
CountryRegion	countryRegion	Country or region code	USA
Region	string	State or province	Washington
DocumentNumber	string	National identity card number	WDLABCD456DG
DocumentDiscriminator	string	National identity card document discriminator	12645646464554646456464544
FirstName	string	Given name and middle initial if applicable	LIAM R.
LastName	string	Surname	TALBOT
Address	address	Address	123 STREET ADDRESS YOUR CITY WA 99999-1234
DateOfBirth	date	Date of birth	01/06/1958
DateOfExpiration	date	Date of expiration	08/12/2020
DateOfIssue	date	Date of issue	08/12/2012
EyeColor	string	Eye color	BLU
HairColor	string	Hair color	BRO
Height	string	Height	5'11"
Weight	string	Weight	185LB
Sex	string	Sex	M

idDocument.residencePermit

Field	Type	Description	Example
CountryRegion	countryRegion	Country or region code	USA
DocumentNumber	string	Residence permit number	WDLABCD456DG
FirstName	string	Given name and middle initial if applicable	LIAM R.
LastName	string	Surname	TALBOT
DateOfBirth	date	Date of birth	01/06/1958
DateOfExpiration	date	Date of expiration	08/12/2020
DateOfIssue	date	Date of issue	08/12/2012
Sex	string	Sex	M
PlaceOfBirth	string	Place of birth	Germany
Category	string	Permit category	DV2
Address	string	Address	123 STREET ADDRESS YOUR CITY WA 99999-1234

idDocument.usSocialSecurityCard

Field	Type	Description	Example
DocumentNumber	string	Social security card number	WDLABCD456DG
FirstName	string	Given name and middle initial if applicable	LIAM R.
LastName	string	Surname	TALBOT
DateOfIssue	date	Date of issue	08/12/2012

idDocument

Field	Type	Description	Example
Address	address	Address	123 STREET ADDRESS YOUR CITY WA 99999-1234
DocumentNumber	string	Driver license number	WDLABCD456DG
FirstName	string	Given name and middle initial if applicable	LIAM R.
LastName	string	Surname	TALBOT
DateOfBirth	date	Date of birth	01/06/1958
DateOfExpiration	date	Date of expiration	08/12/2020

invoice

Field	Type	Description	Example
CustomerName	string	Customer being invoiced	Microsoft Corp
CustomerId	string	Reference ID for the customer	CID-12345
PurchaseOrder	string	A purchase order reference number	PO-3333
InvoiceId	string	ID for this specific invoice (often 'Invoice Number')	INV-100
InvoiceDate	date	Date the invoice was issued	11/15/2019
DueDate	date	Date payment for this invoice is due	12/15/2019
VendorName	string	Vendor who has created this invoice	CONTOSO LTD.
VendorAddress	address	Mailing address for the Vendor	123 456th St New York, NY, 10001
VendorAddressRecipient	string	Name associated with the VendorAddress	Contoso Headquarters
CustomerAddress	address	Mailing address for the Customer	123 Other St, Redmond WA, 98052
CustomerAddressRecipient	string	Name associated with the CustomerAddress	Microsoft Corp
BillingAddress	address	Explicit billing address for the customer	123 Bill St, Redmond WA, 98052
BillingAddressRecipient	string	Name associated with the BillingAddress	Microsoft Services
ShippingAddress	address	Explicit shipping address for the customer	123 Ship St, Redmond WA, 98052
ShippingAddressRecipient	string	Name associated with the ShippingAddress	Microsoft Delivery
SubTotal	currency	Subtotal field identified on this invoice	$100.00
TotalDiscount	currency	Total discount field identified on this invoice	$5.00
TotalTax	currency	Total tax field identified on this invoice	$10.00
InvoiceTotal	currency	Total new charges associated with this invoice	$110.00
AmountDue	currency	Total Amount Due to the vendor	$610.00
PreviousUnpaidBalance	currency	Explicit previously unpaid balance	$500.00
RemittanceAddress	address	Explicit remittance or payment address for the customer	123 Remit St New York, NY, 10001
RemittanceAddressRecipient	string	Name associated with the RemittanceAddress	Contoso Billing
ServiceAddress	address	Explicit service address or property address for the customer	123 Service St, Redmond WA, 98052
ServiceAddressRecipient	string	Name associated with the ServiceAddress	Microsoft Services
ServiceStartDate	date	First date for the service period (for example, a utility bill service period)	10/14/2019
ServiceEndDate	date	End date for the service period (for example, a utility bill service period)	11/14/2019
VendorTaxId	string	The government ID number associated with the vendor	123456-7
CustomerTaxId	string	The government ID number associated with the customer	765432-1
PaymentTerm	string	The terms under which the payment is meant to be paid	Net90
PaymentDetails	array	List of payment details
PaymentDetails.*	object	A single payment detail
PaymentDetails.*.IBAN	string	International bank account number	DE 94 700 700 100 029 49 00 00
PaymentDetails.*.SWIFT	string	ISO9362, an international standard for Business Identifier Codes (BIC)	DEUTDEMMXXX
TaxDetails	array	List of tax details
TaxDetails.*	object	A single tax detail
TaxDetails.*.Amount	currency	The amount of the tax detail	29,520.00
TaxDetails.*.Rate	string	The rate of the tax detail	18 %
Items	array	List of line items
Items.*	object	A single line item	3/4/2021 A123 Consulting Services 2 hours $30.00 10% $60.00
Items.*.Amount	currency	The amount of the line item	$60.00
Items.*.Date	date	Date corresponding to each line item. Often it is a date the line item was shipped	3/4/2021
Items.*.Description	string	The text description for the invoice line item	Consulting service
Items.*.Quantity	number	The quantity for this invoice line item	2
Items.*.ProductCode	string	Product code, product number, or SKU associated with the specific line item	A123
Items.*.Tax	currency	Tax associated with each line item. Possible values include tax amount, tax %, and tax Y/N	$6.00
Items.*.TaxRate	string	Tax rate associated with each line item	18 %
Items.*.Unit	string	The unit of the line item, e.g, kg, lb etc.	hours
Items.*.UnitPrice	currency	The net or gross price (depending on the gross invoice setting of the invoice) of one unit of this item	$30.00

receipt

Field	Type	Description	Example
MerchantName	string	Name of the merchant issuing the receipt	Contoso
MerchantPhoneNumber	phoneNumber	Listed phone number of merchant	987-654-3210
MerchantAddress	address	Listed address of merchant	123 Main St Redmond WA 98052
Total	number	Full transaction total of receipt	$14.34
TransactionDate	date	Date the receipt was issued	June 06, 2019
TransactionTime	time	Time the receipt was issued	4:49 PM
Subtotal	number	Subtotal of receipt, often before taxes are applied	$12.34
TotalTax	number	Tax on receipt, often sales tax or equivalent	$2.00
Tip	number	Tip included by buyer	$1.00
Items	array
Items.*	object	Extracted line item	1 Surface Pro 6 $999.00 $999.00
Items.*.TotalPrice	number	Total price of line item	$999.00
Items.*.Description	string	Item description	Surface Pro 6
Items.*.Quantity	number	Quantity of each item	1
Items.*.Price	number	Individual price of each item unit	$999.00
Items.*.ProductCode	string	Product code, product number, or SKU associated with the specific line item	A123
Items.*.QuantityUnit	string	Quantity unit of each item
TaxDetails	array
TaxDetails.*	object	Extracted line item	1 Surface Pro 6 $999.00 $999.00
TaxDetails.*.Amount	currency	The amount of the tax detail	$999.00

receipt.retailMeal

Field	Type	Description	Example
MerchantName	string	Name of the merchant issuing the receipt	Contoso
MerchantPhoneNumber	phoneNumber	Listed phone number of merchant	987-654-3210
MerchantAddress	address	Listed address of merchant	123 Main St Redmond WA 98052
Total	number	Full transaction total of receipt	$14.34
TransactionDate	date	Date the receipt was issued	June 06, 2019
TransactionTime	time	Time the receipt was issued	4:49 PM
Subtotal	number	Subtotal of receipt, often before taxes are applied	$12.34
TotalTax	number	Tax on receipt, often sales tax or equivalent	$2.00
Tip	number	Tip included by buyer	$1.00
Items	array
Items.*	object	Extracted line item	1 Surface Pro 6 $999.00 $999.00
Items.*.TotalPrice	number	Total price of line item	$999.00
Items.*.Description	string	Item description	Surface Pro 6
Items.*.Quantity	number	Quantity of each item	1
Items.*.Price	number	Individual price of each item unit	$999.00
Items.*.ProductCode	string	Product code, product number, or SKU associated with the specific line item	A123
Items.*.QuantityUnit	string	Quantity unit of each item
TaxDetails	array
TaxDetails.*	object	Extracted line item	1 Surface Pro 6 $999.00 $999.00
TaxDetails.*.Amount	currency	The amount of the tax detail	$999.00

receipt.creditCard

Field	Type	Description	Example
MerchantName	string	Name of the merchant issuing the receipt	Contoso
MerchantPhoneNumber	phoneNumber	Listed phone number of merchant	987-654-3210
MerchantAddress	address	Listed address of merchant	123 Main St Redmond WA 98052
Total	number	Full transaction total of receipt	$14.34
TransactionDate	date	Date the receipt was issued	June 06, 2019
TransactionTime	time	Time the receipt was issued	4:49 PM
Subtotal	number	Subtotal of receipt, often before taxes are applied	$12.34
TotalTax	number	Tax on receipt, often sales tax or equivalent	$2.00
Tip	number	Tip included by buyer	$1.00
Items	array
Items.*	object	Extracted line item	1 Surface Pro 6 $999.00 $999.00
Items.*.TotalPrice	number	Total price of line item	$999.00
Items.*.Description	string	Item description	Surface Pro 6
Items.*.Quantity	number	Quantity of each item	1
Items.*.Price	number	Individual price of each item unit	$999.00
Items.*.ProductCode	string	Product code, product number, or SKU associated with the specific line item	A123
Items.*.QuantityUnit	string	Quantity unit of each item
TaxDetails	array
TaxDetails.*	object	Extracted line item	1 Surface Pro 6 $999.00 $999.00
TaxDetails.*.Amount	currency	The amount of the tax detail	$999.00

receipt.gas

Field	Type	Description	Example
MerchantName	string	Name of the merchant issuing the receipt	Contoso
MerchantPhoneNumber	phoneNumber	Listed phone number of merchant	987-654-3210
MerchantAddress	address	Listed address of merchant	123 Main St Redmond WA 98052
Total	number	Full transaction total of receipt	$14.34
TransactionDate	date	Date the receipt was issued	June 06, 2019
TransactionTime	time	Time the receipt was issued	4:49 PM
Subtotal	number	Subtotal of receipt, often before taxes are applied	$12.34
TotalTax	number	Tax on receipt, often sales tax or equivalent	$2.00
Tip	number	Tip included by buyer	$1.00
Items	array
Items.*	object	Extracted line item	1 Surface Pro 6 $999.00 $999.00
Items.*.TotalPrice	number	Total price of line item	$999.00
Items.*.Description	string	Item description	Surface Pro 6
Items.*.Quantity	number	Quantity of each item	1
Items.*.Price	number	Individual price of each item unit	$999.00
Items.*.ProductCode	string	Product code, product number, or SKU associated with the specific line item	A123
Items.*.QuantityUnit	string	Quantity unit of each item
TaxDetails	array
TaxDetails.*	object	Extracted line item	1 Surface Pro 6 $999.00 $999.00
TaxDetails.*.Amount	currency	The amount of the tax detail	$999.00

receipt.parking

Field	Type	Description	Example
MerchantName	string	Name of the merchant issuing the receipt	Contoso
MerchantPhoneNumber	phoneNumber	Listed phone number of merchant	987-654-3210
MerchantAddress	address	Listed address of merchant	123 Main St Redmond WA 98052
Total	number	Full transaction total of receipt	$14.34
TransactionDate	date	Date the receipt was issued	June 06, 2019
TransactionTime	time	Time the receipt was issued	4:49 PM
Subtotal	number	Subtotal of receipt, often before taxes are applied	$12.34
TotalTax	number	Tax on receipt, often sales tax or equivalent	$2.00
Tip	number	Tip included by buyer	$1.00
Items	array
Items.*	object	Extracted line item	1 Surface Pro 6 $999.00 $999.00
Items.*.TotalPrice	number	Total price of line item	$999.00
Items.*.Description	string	Item description	Surface Pro 6
Items.*.Quantity	number	Quantity of each item	1
Items.*.Price	number	Individual price of each item unit	$999.00
Items.*.ProductCode	string	Product code, product number, or SKU associated with the specific line item	A123
Items.*.QuantityUnit	string	Quantity unit of each item
TaxDetails	array
TaxDetails.*	object	Extracted line item	1 Surface Pro 6 $999.00 $999.00
TaxDetails.*.Amount	currency	The amount of the tax detail	$999.00

receipt.hotel

Field	Type	Description	Example
MerchantName	string	Name of the merchant issuing the receipt	Contoso
MerchantPhoneNumber	phoneNumber	Listed phone number of merchant	987-654-3210
MerchantAddress	address	Listed address of merchant	123 Main St Redmond WA 98052
Total	number	Full transaction total of receipt	$14.34
ArrivalDate	date	Date of arrival	27Mar21
DepartureDate	date	Date of departure	28Mar21
Currency	string	Currency unit of receipt amounts (ISO 4217), or 'MIXED' if multiple values are found	USD
MerchantAliases	array
MerchantAliases.*	string	Alternative name of merchant	Contoso (R)
Items	array
Items.*	object	Extracted line item	1 Surface Pro 6 $999.00 $999.00
Items.*.TotalPrice	number	Total price of line item	$999.00
Items.*.Description	string	Item description	Room Charge
Items.*.Date	date	Item date	27Mar21
Items.*.Category	string	Item category	Room

healthInsuranceCard.us

Field	Type	Description	Example
Insurer	string	Health insurance provider name	PREMERA BLUE CROSS
Member	object
Member.Name	string	Member name	ANGEL BROWN
Member.BirthDate	date	Member date of birth	01/06/1958
Member.Employer	string	Member name employer	Microsoft
Member.Gender	string	Member gender	M
Member.IdNumberSuffix	string	Identification Number Suffix as it appears on some health insurance cards	01
Dependents	array	Array holding list of dependents, ordered where possible by membership suffix value
Dependents.*	object
Dependents.*.Name	string	Dependent name	01
IdNumber	object
IdNumber.Prefix	string	Identification Number Prefix as it appears on some health insurance cards	ABC
IdNumber.Number	string	Identification Number	123456789
GroupNumber	string	Insurance Group Number	1000000
PrescriptionInfo	object
PrescriptionInfo.Issuer	string	ANSI issuer identification number (IIN)	(80840) 300-11908-77
PrescriptionInfo.RxBIN	string	Prescription issued BIN number	987654
PrescriptionInfo.RxPCN	string	Prescription processor control number	63200305
PrescriptionInfo.RxGrp	string	Prescription group number	BCAAXYZ
PrescriptionInfo.RxId	string	Prescription identification number. If not present, will default to membership id number	P97020065
PrescriptionInfo.RxPlan	string	Prescription Plan number	A1
Pbm	string	Pharmacy Benefit Manager for the plan	CVS CAREMARK
EffectiveDate	date	Date from which the plan is effective	08/12/2012
Copays	array	Array holding list of CoPay Benefits
Copays.*	object
Copays.*.Benefit	string	Co-Pay Benefit name	Deductible
Copays.*.Amount	currency	Co-Pay required amount	$1,500
Payer	object
Payer.Id	string	Payer Id Number	89063
Payer.Address	address	Payer address	123 Service St, Redmond WA, 98052
Payer.PhoneNumber	phoneNumber	Payer phone number	+1 (987) 213-5674
Plan	object
Plan.Number	string	Plan number	456
Plan.Name	string	Plan name - If see Medicaid -> then medicaid	HEALTH SAVINGS PLAN
Plan.Type	string	Plan type	PPO
MedicareMedicaidInfo	object
MedicareMedicaidInfo.Id	string	Medicare or Medicaid number	1AB2-CD3-EF45
MedicareMedicaidInfo.PartAEffectiveDate	date	Effective date of Medicare Part A	01-01-2023
MedicareMedicaidInfo.PartBEffectiveDate	date	Effective date of Medicare Part B	01-01-2023

vaccination.covid19.us

Field	Type	Description	Example
CardHolderInfo	object
CardHolderInfo.FirstName	string	Cardholder first name	John
CardHolderInfo.LastNames	string	Cardholder last name	Contoso
CardHolderInfo.DateOfBirth	date	Cardholder date of birth	12/25/1980
CardHolderInfo.PatientNumber	string	Cardholder Patient number if present	AB123456789
Vaccines	array	Array holding all the Covid-19 shots received by the cardholder
Vaccines.*	object
Vaccines.*.Manufacturer	string	Manifacturer of the vaccine dose	Pfizer Covid-19 vaccine
Vaccines.*.DateAdministered	date	Date at which the dose was administrated	12/25/2022

tax.us.w2

Field	Type	Description	Example
W2FormVariant	string	IRS W2 Form variant. This field can have the one of the following values: 'W-2', 'W-2AS', 'W-2CM', 'W-2GU' or 'W-2VI'	W-2
TaxYear	string	Form tax year	2021
W2Copy	string	W2 form copy version along with printed instruction realted to this copy	Copy A—For Social Security Administration
Employee	object
Employee.SocialSecurityNumber	string	Employee social security number. IRS W2 form field a. eg: '123-45-6789'	123-45-6789
Employee.Name	string	Employee's first name, middle full/initials name, last name and suffix. IRS W2 form field e	John Contonso
Employee.Address	address	Employee's address. Part of IRS W2 form field f	123 Microsoft way, Redmond WA, 98123
ControlNumber	string	W2 Form control number. IRS W2 form field d	0AB12 D345 7890
Employer	object
Employer.IdNumber	string	Employer's identification number. IRS W2 form field b	12-3456789
Employer.Name	string	Employer's name. Part of IRS W2 form field c	Fabrikam
Employer.Address	address	Employer's address. Part of IRS W2 form field c	321 Microsoft way, Redmond WA, 98123
WagesTipsAndOtherCompensation	number	Wages, tips, and other compensation amount in USD. IRS W2 form field 1	1234567.89
FederalIncomeTaxWithheld	number	Federal income tax withheld amount in USD. IRS W2 form field 2	1234567.89
SocialSecurityWages	number	Social security wages amount in USD. IRS W2 form field 3	1234567.89
SocialSecurityTaxWithheld	number	Social security tax withheld amount in USD. IRS W2 form field 4	1234567.89
MedicareWagesAndTips	number	Medicare wages and tips amount in USD. IRS W2 form field 5	1234567.89
MedicareTaxWithheld	number	Medicare tax withheld amount in USD. IRS W2 form field 6	1234567.89
SocialSecurityTips	number	Social security tips amount in USD. IRS W2 form field 7	1234567.89
AllocatedTips	number	Allocated tips in USD. IRS W2 form field 8	1234567.89
VerificationCode	string	W2 form verification code. IRS W2 form field 9	AB123456
DependentCareBenefits	number	Dependent care benefits amount in USD. IRS W2 form field 10	1234567.89
NonQualifiedPlans	number	Non-qualified plans amount in USD. IRS W2 form field 11	1234567.89
AdditionalInfo	array	Array holding W2 Codes. IRS W2 form field 12
AdditionalInfo.*	object
AdditionalInfo.*.LetterCode	string	Please refer to https://www.irs.gov/pub/irs-pdf/iw2w3.pdf for more details on IRS W2 box 12's letter code	A
AdditionalInfo.*.Amount	number	Code amount in USD	1234567.89
IsStatutoryEmployee	string	Part of IRS W2 form field 13. Can be 'true' or 'false'	true
IsRetirementPlan	string	Part of IRS W2 form field 13. Can be 'true' or 'false'	true
IsThirdPartySickPay	string	Part of IRS W2 form field 13. Can be 'true' or 'false'	true
Other	string	Content of IRS W2 form field 14	SICK LV WAGES SBJT TO $511/DAY LIMIT 1356
StateTaxInfos	array	State tax-related information. content of IRS W2 form field 15 to 17
StateTaxInfos.*	object
StateTaxInfos.*.State	string	Two letter state code. Part of IRS W2 form field 15	WA
StateTaxInfos.*.EmployerStateIdNumber	string	Employer state ID number. Part of IRS W2 form field 15	1234567
StateTaxInfos.*.StateWagesTipsEtc	number	State wages, tips, etc amount in USD. IRS W2 form field 16	1234567.89
StateTaxInfos.*.StateIncomeTax	number	State income tax amount in USD. IRS W2 form field 17	1234567.89
LocalTaxInfos	array	Local tax-related information. Content of IRS W2 form field 18 to 20
LocalTaxInfos.*	object
LocalTaxInfos.*.LocalWagesTipsEtc	number	Local wages, tips, etc amount in USD. Part of IRS W2 form field 18	1234567.89
LocalTaxInfos.*.LocalIncomeTax	number	Local income tax amount in USD. Part of IRS W2 form field 19	1234567.89
LocalTaxInfos.*.LocalityName	string	Locality name. Part of IRS W2 form field 20	Redmond

Error

Form Recognizer uses an unified design to represent all errors encountered in the REST APIs. Whenever an API operations returns a 4xx or 5xx status code, additional information about the error are returned in the response JSON body as follows:

       
   {
     "error": {
       "code": "InvalidRequest",
       "message": "Invalid request.",
       "innererror": {
         "code": "InvalidContent",
         "message": "The file format is unsupported or corrupted. Refer to documentation for the list of supported formats."
       }
     }
   }

For long-running operations where multiple errors may be encountered, the top-level error code is set to the most severe error, with the individual errors listed under the error.details property. In such scenarios, the target property of each individual error specifies the trigger of the error.

       
   {
       "status": "failed",
       "createdDateTime": "2021-07-14T10:17:51Z",
       "lastUpdatedDateTime": "2021-07-14T10:17:51Z",
       "error": {
           "code": "InternalServerError",
           "message": "An unexpected error occurred.",
           "details": [
               {
                   "code": "InternalServerError",
                   "message": "An unexpected error occurred."
               },
               {
                   "code": "InvalidContentDimensions",
                   "message": "The input image dimensions are out of range. Refer to documentation for supported image dimensions.",
                   "target": "2"
               }
           ]
       }
   }

application/json

{
    "status": "succeeded",
    "createdDateTime": "2022-08-31T12:42:07Z",
    "lastUpdatedDateTime": "2022-08-31T12:42:13Z",
    "analyzeResult": {
      // Basic analyze result metadata
      "apiVersion": "2022-08-31",   // REST API version used
      "modelId": "prebuilt-invoice",        // ModelId used
      "stringIndexType": "textElements",    // Character unit used for string offsets and lengths: textElements, unicodeCodePoint, utf16CodeUnit
      // Concatenated content in global reading order across pages.
      // Words are generally delimited by space, except CJK (Chinese, Japanese, Korean) characters.
      // Lines and selection marks are generally delimited by newline character.
      // Selection marks are represented in Markdown emoji syntax (:selected:, :unselected:).
      "content": "CONTOSO LTD.\nINVOICE\nContoso Headquarters...",
      "pages": [                            // List of pages analyzed
        {
          // Basic page metadata
          "pageNumber": 1,                  // 1-indexed page number
          "angle": 0,                       // Orientation of content in clockwise direction (degree)
          "width": 0,                       // Page width
          "height": 0,                      // Page height
          "unit": "pixel",                  // Unit for width, height, and bounding box coordinates
          "kind": "document",               // Kind of document page: document, sheet, slide or image.
          "spans": [                        // Parts of top-level content covered by page
            {
              "offset": 0,                  // Offset in content
              "length": 7                   // Length in content
            }
          ],
          // List of words in page
          "words": [
            {
              "content": "CONTOSO",         // Equivalent to $.content.Substring(span.offset, span.length)
              "boundingBox": [ ... ],       // Position in page
              "confidence": 0.99,           // Extraction confidence
              "span": { ... }               // Part of top-level content covered by word
            }, ...
          ],
          // List of selectionMarks in page
          "selectionMarks": [
            {
              "state": "selected",          // Selection state: selected, unselected
              "boundingBox": [ ... ],       // Position in page
              "confidence": 0.95,           // Extraction confidence
              "span": { ... }               // Part of top-level content covered by selection mark
            }, ...
          ],
          // List of lines in page
          "lines": [
            {
              "content": "CONTOSO LTD.",    // Concatenated content of line (may contain both words and selectionMarks)
              "boundingBox": [ ... ],       // Position in page
              "spans": [ ... ],             // Parts of top-level content covered by line
            }, ...
          ],
          //Extracted annotations from the page.
          "annotations":[
            {
              "kind": "check",              // Annotation kind. 
              "polygon": [... ],              // Bounding polygon of the annotation.
              "confidence": 0.95,             // Confidence of correctly extracting the annotation. 
            },
          ],
          // Extracted barcodes from the page.
          "barcodes":[
            {
              "kind": "QRCode",            // Barcode kind.
              "value": "string",           // Barcode value.
              "polygon": [... ],            // Bounding polygon of the barcode.
              "span": { ... },              // Location of the barcode in the reading order concatenated content.
              "confidence": 0.95,           // Confidence of correctly extracting the barcode.
            }
          ],
          // Extracted formulas from the page.
          "formulas":[
            {
              "kind": "inline",            // Formula kind.
              "value": "string",           // LaTex expression describing the formula.
              "polygon": [... ],            // Bounding polygon of the formula.
              "span": { ... },             // Location of the formula in the reading order concatenated content.
              "confidence": 0.95,           // Confidence of correctly extracting the formula.
            }
          ],
          //Extracted images from the page.
          "images":[
            {
              "polygon": [... ],            // Bounding polygon of the image.
              "span": { ... },              // Location of the image in the reading order concatenated content.
              "confidence": 0.95,           // CConfidence of correctly identifying the image.
              "pageNumber": 1,             // 1-based page number of the page that contains the image.
            }
          ]
        }, ...
      ],
      // List of extracted tables
      "tables": [
        {
          "rowCount": 1,                    // Number of rows in table
          "columnCount": 1,                 // Number of columns in table
          "boundingRegions": [              // Bounding boxes potentially across pages covered by table
            {
              "pageNumber": 1,              // 1-indexed page number
              "boundingBox": [ ... ],       // Bounding box
            }
          ],
          "spans": [ ... ],                 // Parts of top-level content covered by table
          // List of cells in table
          "cells": [
            {
              "kind": "stubHead",           // Cell kind: content (default), rowHeader, columnHeader, stubHead, description
              "rowIndex": 0,                // 0-indexed row position of cell
              "columnIndex": 0,             // 0-indexed column position of cell
              "rowSpan": 1,                 // Number of rows spanned by cell (default=1)
              "columnSpan": 1,              // Number of columns spanned by cell (default=1)
              "content": "SALESPERSON",     // Concatenated content of cell
              "boundingRegions": [ ... ],   // Bounding regions covered by cell
              "spans": [ ... ]              // Parts of top-level content covered by cell
            }, ...
          ]
        }, ...
      ],
      // List of extracted key-value pairs
      "keyValuePairs": [
        {
          "key": {                          // Extracted key
            "content": "INVOICE:",          // Key content
            "boundingRegions": [ ... ],     // Key bounding regions
            "spans": [ ... ]                // Key spans
          },
          "value": {                        // Extracted value corresponding to key, if any
            "content": "INV-100",           // Value content
            "boundingRegions": [ ... ],     // Value bounding regions
            "spans": [ ... ]                // Value spans
          },
          "commonName": "commonName 1",     // Common name of the key-value pair.
          "confidence": 0.95                // Extraction confidence
        }, ...
      ],
      // List of extracted entities
      "entities": [
        {
          "category": "DateTime",           // Primary entity category
          "subCategory": "Date",            // Secondary entity category
          "content": "11/15/2019",          // Entity content
          "boundingRegions": [ ... ],       // Entity bounding regions
          "spans": [ ... ],                 // Entity spans
          "confidence": 0.99                // Extraction confidence
        }, ...
      ],
      // List of extracted styles
      "styles": [
        {
          "isHandwritten": true,            // Is content in this style handwritten?
          "spans": [ ... ],                 // Spans covered by this style
          "confidence": 0.95,               // Detection confidence
          "similarFontFamily": "Arial",     // Visually most similar font from among the set of supported font families, with fallback fonts following CSS convention (ex. 'Arial, sans-serif').
          "fontStyle": "normal"             //Font style.
          "fontWeight": "bold",             //Font weight.
          "color": "#00ffbb",               //Foreground color in #rrggbb hexadecimal format.
          "backgroundColor": "#ff0000",     //Background color in #rrggbb hexadecimal format.
        }, ...
      ],
      // List of extracted documents
      "documents": [
        {
          "docType": "invoice",             // Classified document type (model dependent)
          "boundingRegions": [ ... ],       // Document bounding regions
          "spans": [ ... ],                 // Document spans
          "confidence": 0.99,               // Document splitting/classification confidence
          // List of extracted fields
          "fields": {
            "VendorName": {                 // Field name (docType dependent)
              "type": "string",             // Field value type: string, number, array, object, ...
              "valueString": "CONTOSO LTD.",// Normalized field value
              "content": "CONTOSO LTD.",    // Raw extracted field content
              "boundingRegions": [ ... ],   // Field bounding regions
              "spans": [ ... ],             // Field spans
              "confidence": 0.99            // Extraction confidence
            }, ...
          }
        }, ...
      ]
    }
  }

Response 404

The top-level error.code property can be one of the following:

Error Code	Message
NotFound	Resource not found.

When possible, additional details are specified in the innererror property:

Top Error Code	Inner Error Code	Message
NotFound	OperationNotFound	The requested operation was not found. The identifier may be invalid or the operation may have expired.

application/json

{
  "error": {
    "code": "NotFound",
    "message": "Resource not found.",
    "innererror": {
      "code": "OperationNotFound",
      "message": "The requested operation was not found. The identifier may be invalid or the operation may have expired."
    }
  }
}

Response 500

The top-level error.code property can be one of the following:

Error Code	Message
InternalServerError	An unexpected error occurred.

When possible, additional details are specified in the innererror property:

Top Error Code	Inner Error Code	Message
InternalServerError	Unknow	Unknow error.

application/json

{
  "error": {
    "code": "InternalServerError",
    "message": "An unexpected error occurred.",
    "innererror": {
      "code": "Unknown",
      "message": "Unknown error."
    }
  }
}

Response 503

The top-level error.code property can be one of the following:

Error Code	Message
ServiceUnavailable	A transient error has occurred. Please try again.

When possible, additional details are specified in the innererror property:

Top Error Code	Inner Error Code	Message
ServiceUnavailable	ServiceUnavailable	A transient error has occurred. Please try again.

application/json

{
  "error": {
    "code": "ServiceUnavailable",
    "message": "A transient error has occurred. Please try again.",
    "innererror": {
      "code": "ServiceUnavailable",
      "message": "A transient error has occurred. Please try again."
    }
  }
}

Code samples

@ECHO OFF

curl -v -X GET "https://*.cognitiveservices.azure.com/formrecognizer/documentModels/{modelId}/analyzeResults/{resultId}?api-version=2022-08-31"
-H "Ocp-Apim-Subscription-Key: {subscription key}"

--data-ascii "{body}"

using System;
using System.Net.Http.Headers;
using System.Text;
using System.Net.Http;
using System.Web;

namespace CSHttpClientSample
{
    static class Program
    {
        static void Main()
        {
            MakeRequest();
            Console.WriteLine("Hit ENTER to exit...");
            Console.ReadLine();
        }
        
        static async void MakeRequest()
        {
            var client = new HttpClient();
            var queryString = HttpUtility.ParseQueryString(string.Empty);

            // Request headers
            client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

            var uri = "https://*.cognitiveservices.azure.com/formrecognizer/documentModels/{modelId}/analyzeResults/{resultId}?api-version=2022-08-31&" + queryString;

            var response = await client.GetAsync(uri);
        }
    }
}

// // This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
import java.net.URI;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

public class JavaSample 
{
    public static void main(String[] args) 
    {
        HttpClient httpclient = HttpClients.createDefault();

        try
        {
            URIBuilder builder = new URIBuilder("https://*.cognitiveservices.azure.com/formrecognizer/documentModels/{modelId}/analyzeResults/{resultId}?api-version=2022-08-31");


            URI uri = builder.build();
            HttpGet request = new HttpGet(uri);
            request.setHeader("Ocp-Apim-Subscription-Key", "{subscription key}");


            // Request body
            StringEntity reqEntity = new StringEntity("{body}");
            request.setEntity(reqEntity);

            HttpResponse response = httpclient.execute(request);
            HttpEntity entity = response.getEntity();

            if (entity != null) 
            {
                System.out.println(EntityUtils.toString(entity));
            }
        }
        catch (Exception e)
        {
            System.out.println(e.getMessage());
        }
    }
}

<!DOCTYPE html>
<html>
<head>
    <title>JSSample</title>
    <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script>
</head>
<body>

<script type="text/javascript">
    $(function() {
        var params = {
            // Request parameters
        };
      
        $.ajax({
            url: "https://*.cognitiveservices.azure.com/formrecognizer/documentModels/{modelId}/analyzeResults/{resultId}?api-version=2022-08-31&" + $.param(params),
            beforeSend: function(xhrObj){
                // Request headers
                xhrObj.setRequestHeader("Ocp-Apim-Subscription-Key","{subscription key}");
            },
            type: "GET",
            // Request body
            data: "{body}",
        })
        .done(function(data) {
            alert("success");
        })
        .fail(function() {
            alert("error");
        });
    });
</script>
</body>
</html>

#import <Foundation/Foundation.h>

int main(int argc, const char * argv[])
{
    NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];
    
    NSString* path = @"https://*.cognitiveservices.azure.com/formrecognizer/documentModels/{modelId}/analyzeResults/{resultId}?api-version=2022-08-31";
    NSArray* array = @[
                         // Request parameters
                         @"entities=true",
                      ];
    
    NSString* string = [array componentsJoinedByString:@"&"];
    path = [path stringByAppendingFormat:@"?%@", string];

    NSLog(@"%@", path);

    NSMutableURLRequest* _request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:path]];
    [_request setHTTPMethod:@"GET"];
    // Request headers
    [_request setValue:@"{subscription key}" forHTTPHeaderField:@"Ocp-Apim-Subscription-Key"];
    // Request body
    [_request setHTTPBody:[@"{body}" dataUsingEncoding:NSUTF8StringEncoding]];
    
    NSURLResponse *response = nil;
    NSError *error = nil;
    NSData* _connectionData = [NSURLConnection sendSynchronousRequest:_request returningResponse:&response error:&error];

    if (nil != error)
    {
        NSLog(@"Error: %@", error);
    }
    else
    {
        NSError* error = nil;
        NSMutableDictionary* json = nil;
        NSString* dataString = [[NSString alloc] initWithData:_connectionData encoding:NSUTF8StringEncoding];
        NSLog(@"%@", dataString);
        
        if (nil != _connectionData)
        {
            json = [NSJSONSerialization JSONObjectWithData:_connectionData options:NSJSONReadingMutableContainers error:&error];
        }
        
        if (error || !json)
        {
            NSLog(@"Could not parse loaded json with error:%@", error);
        }
        
        NSLog(@"%@", json);
        _connectionData = nil;
    }
    
    [pool drain];

    return 0;
}

<?php
// This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
require_once 'HTTP/Request2.php';

$request = new Http_Request2('https://*.cognitiveservices.azure.com/formrecognizer/documentModels/{modelId}/analyzeResults/{resultId}?api-version=2022-08-31');
$url = $request->getUrl();

$headers = array(
    // Request headers
    'Ocp-Apim-Subscription-Key' => '{subscription key}',
);

$request->setHeader($headers);

$parameters = array(
    // Request parameters
);

$url->setQueryVariables($parameters);

$request->setMethod(HTTP_Request2::METHOD_GET);

// Request body
$request->setBody("{body}");

try
{
    $response = $request->send();
    echo $response->getBody();
}
catch (HttpException $ex)
{
    echo $ex;
}

?>

########### Python 2.7 #############
import httplib, urllib, base64

headers = {
    # Request headers
    'Ocp-Apim-Subscription-Key': '{subscription key}',
}

params = urllib.urlencode({
})

try:
    conn = httplib.HTTPSConnection('*.cognitiveservices.azure.com')
    conn.request("GET", "/formrecognizer/documentModels/{modelId}/analyzeResults/{resultId}?api-version=2022-08-31&%s" % params, "{body}", headers)
    response = conn.getresponse()
    data = response.read()
    print(data)
    conn.close()
except Exception as e:
    print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################

########### Python 3.2 #############
import http.client, urllib.request, urllib.parse, urllib.error, base64

headers = {
    # Request headers
    'Ocp-Apim-Subscription-Key': '{subscription key}',
}

params = urllib.parse.urlencode({
})

try:
    conn = http.client.HTTPSConnection('*.cognitiveservices.azure.com')
    conn.request("GET", "/formrecognizer/documentModels/{modelId}/analyzeResults/{resultId}?api-version=2022-08-31&%s" % params, "{body}", headers)
    response = conn.getresponse()
    data = response.read()
    print(data)
    conn.close()
except Exception as e:
    print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################

require 'net/http'

uri = URI('https://*.cognitiveservices.azure.com/formrecognizer/documentModels/{modelId}/analyzeResults/{resultId}?api-version=2022-08-31')
uri.query = URI.encode_www_form({
})

request = Net::HTTP::Get.new(uri.request_uri)
# Request headers
request['Ocp-Apim-Subscription-Key'] = '{subscription key}'
# Request body
request.body = "{body}"

response = Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
    http.request(request)
end

puts response.body