Document AI allows you to take invoices in a variety of formats and return structured data to reduce manual document processing.
The invoice parser extracts both header and line item fields, such as invoice number, supplier name, invoice amount, tax amount, invoice date, due date, and line item amounts.
Request document processing from a smaller file (<=5 pages for most processors) using the
process
method, and larger file requests (files with a large
number of pages) use the
batchProcess
method. The status of batch (asynchronous) requests can be checked using the operations
resource.
Example invoice†:
| † | These annotations are meant to be illustrative, and are not meant to be a comprehensive list of annotations offered by this feature. |
Fields extracted
The following is a list of the exemplar annotations returned in a
Document response object's entities and
entityRelations fields.
This example list may be expanded in current or future API versions:
| Field | Annotations |
|---|---|
entities |
|
entityRelations |
|
Processor details
| File types supported | PDF, TIFF, GIF |
| Maximum number of pages (online/synchronous) | 5 |
| Maximum number of pages (offline/asynchronous/batch) | 2000 |
| Maximum file size | 20Mb |
Small file online processing
Synchronous ("online") requests target a document with a small number of pages and size stored in Cloud Storage. Synchronous requests immediately return a response inline.
The following code samples show you how to process an invoice document.
v1beta2
Select the tab below for your language or environment:
REST & CMD LINE
This sample shows how to use the
process method to request small document processing
(<=5 pages, < 20MB). The example uses the access token for a
service account set up for the project using the Cloud SDK. For
instructions on installing the Cloud SDK, setting up a project with a
service account, and obtaining an access token, see
Before you begin.
The sample
request body
contains required fields (inputConfig) and the field to set
invoice processing (documentType).
Before using any of the request data below, make the following replacements:
- LOCATION: one of the following regional processing options:
us- United Stateseu- European Union
- PROJECT_ID: Your GCP project ID.
- STORAGE_URI: The URI of the document you want to
process stored in a Cloud Storage bucket, including the
gs://prefix. You must at least have read privileges to the file. Example:gs://cloud-samples-data/documentai/invoice.pdf
HTTP method and URL:
POST https://LOCATION-documentai.googleapis.com/v1beta2/projects/PROJECT_ID/locations/LOCATION/documents:process
Request JSON body:
{
"inputConfig":{
"gcsSource":{
"uri":"STORAGE_URI"
},
"mimeType":"application/pdf"
},
"documentType":"invoice"
}
To send your request, choose one of these options:
curl
Save the request body in a file called request.json,
and execute the following command:
curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
https://LOCATION-documentai.googleapis.com/v1beta2/projects/PROJECT_ID/locations/LOCATION/documents:process
PowerShell
Save the request body in a file called request.json,
and execute the following command:
$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-documentai.googleapis.com/v1beta2/projects/PROJECT_ID/locations/LOCATION/documents:process" | Select-Object -Expand Content
If the request is successful, the server returns a 200 OK HTTP status code and the
response in JSON format. The response body contains an instance of
Document, with invoice
entities and
entityRelations
identified.
Large file offline processing
Asynchronous ("offline") requests targets longer documents and allows you to set the number of pages in the output files. This request starts a long-running operation. When this operation finishes it stores output as a JSON file in a specified Cloud Storage bucket.
The following code samples show you how to parse a large invoice document asynchronously.
v1beta2
Select the tab below for your language or environment:
REST & CMD LINE
This sample shows how to send a POST request to the
batchProcess method for large document asynchronous
processing. The example uses the access token for
a service account set up for the project using the Cloud SDK. For
instructions on installing the Cloud SDK, setting up a project with a
service account, and obtaining an access token, see
Before you begin.
The sample
request body
contains required fields
(inputConfig, outputConfig) and the field to
set invoice processing (documentType).
A batchProcess request starts a long-running operation and
stores results in a Cloud Storage bucket. This sample also shows how to
get the status of this long-running operation after it has started.
Send the process request
Before using any of the request data below, make the following replacements:
- LOCATION: one of the following regional processing options:
us- United Stateseu- European Union
- PROJECT_ID: Your GCP project ID.
- STORAGE_URI: The URI of the document you want to
process stored in a Cloud Storage bucket, including the
gs://prefix. You must at least have read privileges to the file. Example:gs://cloud-samples-data/documentai/invoice.pdf
- OUTPUT_BUCKET: A Cloud Storage
bucket/directory to save output files to, expressed in the following form:
gs://bucket/directory/
HTTP method and URL:
POST https://LOCATION-documentai.googleapis.com/v1beta2/projects/PROJECT_ID/locations/LOCATION/documents:batchProcess
Request JSON body:
{
"requests": [
{
"inputConfig": {
"gcsSource": {
"uri": "STORAGE_URI"
},
"mimeType": "application/pdf"
},
"outputConfig": {
"pagesPerShard": 1,
"gcsDestination": {
"uri": "OUTPUT_BUCKET"
}
},
"documentType": "invoice"
}
]
}
To send your request, choose one of these options:
curl
Save the request body in a file called request.json,
and execute the following command:
curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
https://LOCATION-documentai.googleapis.com/v1beta2/projects/PROJECT_ID/locations/LOCATION/documents:batchProcess
PowerShell
Save the request body in a file called request.json,
and execute the following command:
$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-documentai.googleapis.com/v1beta2/projects/PROJECT_ID/locations/LOCATION/documents:batchProcess" | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{
"name": "projects/PROJECT_ID/operations/operation-id"
}
If the request is successful, the Document AI returns the name for your operation.
Get the results
To get the results of your request, you must send a GET
request to the operations resource. The following shows how
to send such a request.
Before using any of the request data below, make the following replacements:
- LOCATION: one of the following regional processing options:
us- United Stateseu- European Union
- PROJECT_ID: Your GCP project ID.
- OPERATION_ID: The ID of your operation. The ID is the last element of the name
of your operation. For example:
- operation name:
projects/PROJECT_ID/locations/LOCATION/operations/bc4e1d412863e626 - operation id:
bc4e1d412863e626
- operation name:
HTTP method and URL:
GET https://LOCATION-documentai.googleapis.com/v1beta2/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID
To send your request, choose one of these options:
curl
Execute the following command:
curl -X GET \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
https://LOCATION-documentai.googleapis.com/v1beta2/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID
PowerShell
Execute the following command:
$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://LOCATION-documentai.googleapis.com/v1beta2/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID" | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{
"name": "projects/BUCKET_ID/locations/LOCATION/operations/OPERATION_ID",
"metadata": {
"@type": "type.googleapis.com/google.cloud.documentai.v1beta2.OperationMetadata",
"state": "SUCCEEDED",
"createTime": "2019-11-19T00:36:37.310474834Z",
"updateTime": "2019-11-19T00:37:10.682615795Z"
},
"done": true,
"response": {
"@type": "type.googleapis.com/google.cloud.documentai.v1beta2.BatchProcessDocumentsResponse",
"responses": [
{
"inputConfig": {
"gcsSource": {
"uri": "gs://INPUT_FILE"
},
"mimeType": "application/pdf"
},
"outputConfig": {
"gcsDestination": {
"uri": "gs://OUTPUT_BUCKET/"
}
}
}
]
}
}
Processing output should look similar to the
following example. Processing output should look similar to the
following example. The response body contains an instance of
Document. In this
Document format the response contains any information
relevant to invoice processing
(
entities and
entityRelations) and batch processing
(shardInfo).
This output is for a publicly accessible PDF file
(gs://cloud-samples-data/documentai/invoice.pdf), with one page per
shard. This file is stored to the specified output Cloud Storage bucket.
output-page-1-to-1.json: