Tutorial: Process your first document
This tutorial walks through a complete Amazon Textract Insights job: you create a project with extraction and a public W-2 blueprint, upload a document, start a job, poll for completion, and read both the extraction and custom extraction results from Amazon S3. It uses the AWS CLI, the example account 111122223333, AWS Region us-east-1, and the buckets amzn-s3-demo-bucket (input) and amzn-s3-demo-destination-bucket (output).
Before you begin, complete Prerequisites and setup.
Step 1: Create a project
Create a project that enables extraction (required) and attaches the public W-2
blueprint for custom extraction. The --extraction-configuration block is
required and must set BoundingBox, a non-empty
Granularity.Types, and OutputFormat.
aws textract create-project \ --region us-east-1 \ --project-name "my-first-project" \ --custom-configuration '{"Blueprints": [{"BlueprintArn": "arn:aws:textract:us-east-1:aws:blueprint/public-w2-form"}]}' \ --extraction-configuration '{"BoundingBox": {"State": "ENABLED"}, "Granularity": {"Types": ["PAGE", "ELEMENT"]}, "OutputFormat": {"TextFormat": {"Types": ["MARKDOWN"]}, "AdditionalFileFormat": {"State": "DISABLED"}}}'
CreateProject is synchronous. It returns the project ARN and a
status:
{ "ProjectArn": "arn:aws:textract:us-east-1:111122223333:project/abcdef123456", "Status": "COMPLETED" }
Step 2: Upload a document
Upload the document you want to process to your input bucket:
aws s3 cp w2.pdf s3://amzn-s3-demo-bucket/w2.pdf --region us-east-1
Step 3: Start the job
Start the analysis, pointing at the input document, the output prefix, and the project ARN from Step 1. The output S3 URI is a prefix; Amazon Textract Insights writes all result files beneath it.
aws textract start-document-insights \ --region us-east-1 \ --input-configuration '{"S3Uri": "s3://amzn-s3-demo-bucket/w2.pdf"}' \ --output-configuration '{"S3Uri": "s3://amzn-s3-demo-destination-bucket/output"}' \ --project-arn "arn:aws:textract:us-east-1:111122223333:project/abcdef123456"
The call returns a job ARN:
{ "JobArn": "arn:aws:textract:us-east-1:111122223333:job/abcdef123456" }
Step 4: Poll for completion
The job runs asynchronously. Poll its status with GetDocumentInsights
using the job ARN:
aws textract get-document-insights \ --region us-east-1 \ --job-arn "arn:aws:textract:us-east-1:111122223333:job/abcdef123456"
The status is one of IN_PROGRESS, SUCCEEDED, or
FAILED. When the status is SUCCEEDED, the response includes the
output location, and you can read the results from Amazon S3. If the status is
FAILED, the response includes ErrorType and
ErrorMessage.
Step 5: Read the job metadata
On success, Amazon Textract Insights writes a job_metadata.json file at
s3://<bucket>/<prefix>/<job-id>/job_metadata.json. It
lists the output paths for each document the job produced. Download it:
aws s3 cp s3://amzn-s3-demo-destination-bucket/output/<job-id>/job_metadata.json . --region us-east-1
The file points at the extraction and custom extraction result for each document:
{ "job_id": "abcdef123456", "output_metadata": [ { "asset_id": 0, "segment_metadata": [ { "extraction_path": "s3://amzn-s3-demo-destination-bucket/output/abcdef123456/0/extraction/0/result.json", "custom_path": "s3://amzn-s3-demo-destination-bucket/output/abcdef123456/0/custom/0/result.json", "custom_status": "MATCH" } ] } ] }
For the full output layout, see Output location and file structure.
Step 6: Read the extraction result
Download the extraction result named by extraction_path:
aws s3 cp s3://amzn-s3-demo-destination-bucket/output/abcdef123456/0/extraction/0/result.json . --region us-east-1
The extraction result contains document metadata, text representations, statistics, and the sections you enabled through granularity. For a detailed field reference, see Extraction results.
Step 7: Read the custom extraction result
Download the custom (blueprint) result named by custom_path:
aws s3 cp s3://amzn-s3-demo-destination-bucket/output/abcdef123456/0/custom/0/result.json . --region us-east-1
The custom extraction result reports which blueprint matched, the extracted field
values in inference_result, and per-field confidence in
explainability_info. The following output is trimmed and uses placeholder
values:
{ "matched_blueprint": { "arn": "arn:aws:textract:us-east-1:aws:blueprint/public-w2-form", "name": "W2-Form", "confidence": 1 }, "document_class": { "type": "W2" }, "inference_result": { "employee_general_info": { "first_name": "Jane", "employee_last_name": "Doe", "ssn": "123-45-6789", "employee_address": "123 Any Street, Anytown, WA 98101", "employee_zip_code": 98101 }, "employer_info": { "employer_name": "Example Corp", "ein": "12-3456789", "employer_address": "123 Any Street, Anytown, WA 98101", "employer_zip_code": 98101 }, "federal_wage_info": { "wages_tips_other_compensation": 68450, "social_security_wages": 68450, "medicare_wages_tips": 68450 }, "federal_tax_info": { "federal_income_tax": 9835, "social_security_tax": 4243.9, "medicare_tax": 992.53 } }, "explainability_info": [ { "employee_general_info": { "first_name": { "success": true, "confidence": 0.9090, "geometry": [ { "boundingBox": { "top": 0.2454, "left": 0.0656, "width": 0.0322, "height": 0.0083 }, "vertices": [ { "x": 0.0656, "y": 0.2454 }, { "x": 0.0979, "y": 0.2454 }, { "x": 0.0979, "y": 0.2537 }, { "x": 0.0656, "y": 0.2537 } ], "token_scores": [1, 1], "page": 1, "word_references": [{ "word_index": 64, "page_index": 0 }] } ], "type": "string", "value": "Jane" } }, "federal_wage_info": { "wages_tips_other_compensation": { "success": true, "confidence": 0.9235, "geometry": ["..."], "type": "number", "value": 68450 } } } ] }
A per-field confidence score appears in the explainability_info block
that mirrors inference_result. Fields that are not found return an empty
string. Use the confidence scores to decide which fields you can auto-accept and which
you route to human review. For the full structure, see Custom extraction with blueprints.
Next steps
-
Learn the job model and project configuration in How Amazon Textract Insights works and Working with projects.
-
Explore the extraction results in detail in Extraction results.