Amazon Textract: Setup and Testing Walkthrough — 1

What Amazon Textract is?

Amazon Textract is an AWS service that reads documents and returns their contents as structured data. You give it a scanned page, photo or PDF, and it returns the text it found along with where each piece sits on the page.

It goes beyond plain OCR in two ways. It can return tables as rows and columns, and it can pair form labels with their values, such as Invoice Number: with INV-2026-00417.

Textract is a managed API with nothing to deploy. You call it from the AWS CLI or an SDK, and you pay per page processed.

The two ways to call it

Synchronous calls return the result in the same call. They accept PNG, JPEG and single-page PDF, read from an S3 object or from raw bytes.

• DetectDocumentText returns text only.
• AnalyzeDocument returns text, tables and forms.

Asynchronous calls return a job ID, and you fetch the results when the job finishes. They accept multi-page PDF and TIFF plus everything the synchronous calls accept, and read from an S3 object only.

• StartDocumentTextDetection, then GetDocumentTextDetection, for text only.
• StartDocumentAnalysis, then GetDocumentAnalysis, for text, tables and forms.

How it works with S3

Textract does not store your documents. Each call reads the object from S3 at that moment, using the caller’s own credentials. Two consequences follow, and both show up in the tests below:

• The caller needs s3:GetObject on the file, and the bucket must be in the same region as the Textract call.
• If the file is deleted, the next call on it fails.

Environment

All commands ran from a Mac terminal with AWS CLI v2, signed in through IAM Identity Center (SSO).

• Region: us-east-2 (Ohio)
• Bucket: textract-test-oh-dev-01
• Multi-page test file: Budget_Letter_2027.pdf (105.0 KB)
• Single-page test file: textract_sample.pdf, a made-up one-page invoice with a paragraph, six label/value pairs and a table

Before running anything, sign in and select the profile:

aws sso login --profile aiservices-dev
export AWS_PROFILE=aiservices-dev
aws sts get-caller-identity

The last command confirmed the session was using the AWSReservedSSO_AdministratorAccess role in the AiServicesDev account.

Step 1: Create the S3 bucket

The bucket can be in the AWS console as well as from terminal.

1. Search for S3 and click Create bucket.
2. Enter the bucket name textract-test-oh-dev-01. Bucket names must be unique across all of AWS.
3. Leave Block all public access ticked and keep the other defaults.
4. Click Create bucket. Alternatively, if you want to create from terminal

aws s3api create-bucket --bucket textract-test-oh-dev-01 --region us-east-2

Result: the bucket textract-test-oh-dev-01 exists in us-east-2, private, with versioning off (the default). With versioning off, a deleted file cannot be recovered.

Press enter or click to view image in full size

A least-privilege IAM policy

The tests above ran under AdministratorAccess, which already allows everything. An application or Lambda should use a narrower policy instead. This one was drafted for the test bucket; create it under IAM > Policies > Create policy > JSON.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "Textract",
      "Effect": "Allow",
      "Action": [
        "textract:DetectDocumentText",
        "textract:AnalyzeDocument",
        "textract:StartDocumentTextDetection",
        "textract:GetDocumentTextDetection",
        "textract:StartDocumentAnalysis",
        "textract:GetDocumentAnalysis"
      ],
      "Resource": "*"
    },
    {
      "Sid": "BucketObjects",
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
      "Resource": "arn:aws:s3:::textract-test-oh-dev-01/*"
    },
    {
      "Sid": "BucketList",
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::textract-test-oh-dev-01"
    }
  ]
}

Keep s3:ListBucket in its own statement on the bucket ARN, without /*. Object actions apply to bucket/* and ListBucket applies to the bucket itself. If ListBucket is moved into the /* statement, IAM still saves the policy but listing fails with AccessDenied, and a request for a missing file returns 403 instead of 404.

Step 2: Upload the documents

Upload PDF, through the CLI

Upload a couple of PDF’s a multi page one and a single page one. Process is the same for both files

aws s3 cp textract_sample.pdf s3://textract-test-oh-dev-01/

Step 3: Query the documents

Single-page PDF with the synchronous call: succeeded

The --query filter keeps only the text of each detected line and drops the rest of the JSON.

aws textract detect-document-text \
  --document '{"S3Object":{"Bucket":"textract-test-oh-dev-01","Name":"textract_sample.pdf"}}' \
  --query 'Blocks[?BlockType==`LINE`].Text' --output text

Result (one tab-separated line in the terminal; shown here with one detected line per row):

Northwind Office Supply
Sample Invoice (Textract test document)
This is a single-page test document for Amazon Textract. It contains a paragraph of plain text,
a set of key-value pairs, and a table, so it can be used with both DetectDocumentTex and
AnalyzeDocument.
Invoice Number:
INV-2026-00417
Invoice Date:
October 10, 2026
Due Date:
November 9, 2026
Customer Name:
Jordan Example
Customer ID:
CUST-88213
Payment Terms:
Net 30
Line Items
Item
Description
Qty
Unit Price
Amount
1
Copy paper, letter, case
4
$42.50
$170.00
2
Ballpoint pens, box of 12
10
$6.25
$62.50
3
Desk organizer, black
3
$18.00
$54.00
4
Toner cartridge, HY
2
$89.99
$179.98
Subtotal
$466.48
Tax (7.5%)
$34.99
Total
$501.47
Notes: Please reference the invoice number with your payment. Questions can be sent to
billing@northwind.example.

What the output shows:

• Accuracy: every amount, date and ID matches the PDF. The one miss is DetectDocumentTex, which should read DetectDocumentText.
• Repeatability: the command was run twice and returned identical output.
• Structure: the text comes back flat. Table cells and label/value pairs arrive as separate lines with no link between them. Getting rows, columns and label/value pairs requires analyze-document.

Multi-page PDF with the synchronous call: rejected

aws textract detect-document-text \
  --document '{"S3Object":{"Bucket":"textract-test-oh-dev-01","Name":"Budget_Letter_2027.pdf"}}'

Result:

aws: [ERROR]: An error occurred (UnsupportedDocumentException) when calling the DetectDocumentText operation: Request has unsupported document format

The upload and permissions were fine. detect-document-text is synchronous and accepts only images and single-page PDFs, so it rejects a multi-page PDF with this error. Multi-page PDFs need the asynchronous calls described under "Not yet run". The page count of this file was not checked separately; an encrypted or unusually saved PDF produces the same error.

For multi-page document, we have only one route and that is upload the file into S3 and process it from S3.

Multi-page PDFs: the asynchronous calls

Multi-page read - Full text

aws textract start-document-text-detection \
  --document-location '{"S3Object":{"Bucket":"textract-test-oh-dev-01","Name":"Budget_Letter_2027.pdf"}}'

# Execution results
{
    "JobId": "60835562a77d97904b03f5d05a13c5efa76ab919cae92eecad9d2e691ee663d9"
}

We can query on this Job ID for text details

aws textract get-document-text-detection --job-id 60835562a77d97904b03f5d05a13c5efa76ab919cae92eecad9d2e691ee663d9

This will throw a lot of text back and may be hard to follow. As text will be interlaced with geometry details. If you are interested only in text extraction, here’s what will help

aws textract get-document-text-detection --job-id 60835562a77d97904b03f5d05a13c5efa76ab919cae92eecad9d2e691ee663d9 \
  --query 'Blocks[?BlockType==`LINE`].Text' --output text
# Execution Results
Ramblewood Unit Owners' Association     PO Box 630      Worthington, OH 43085   October 02, 2026        Krishnan Sriram Rama    1975 Ramblebranch Dr        Columbus, OH 43220      RE: 1975 Ramblebranch Dr        Dear Krishnan Sriram Rama,      The Board of Directors of Ramblewood Unit Owners' Association approved the 2027 operating budget. Your      2027 assessment is $402.00, billed monthly beginning 01/01/2027.        The Board remains committed to keeping expenses under control while meeting the association's obligations.  The increase is due to higher operating expenses, funding for the phased mill and pave project, with Phase 1        beginning in 2027, and increased reserve funding.       How Your Assessments Are Determined         Each year, the Board works closely with the management team to develop a responsible budget that ensures        financial stability while maintaining the services and upkeep of the community. The budget process includes:        Reviewing contracted services - Evaluating current service providers, negotiating rates, and obtaining      competitive bids if necessary.  Projecting capital improvements - Identifying upcoming projects, estimating costs, and determining  long-term funding needs.        Analyzing historical and current financials - Reviewing past expenditures, current spending trends, and anticipated cost changes.   Incorporating expected income - Factoring in any non-assessment revenue such as rental income,  late fees, or other sources.        Once total expenses are calculated and expected income is subtracted, the amount is divided among all   owners based on par values, per the governing documents.    Also included with this letter is a copy of the approved budget in a new and improved layout. It now provides       a breakdown of anticipated expenses with increased transparency, along with charts illustrating where   assessments are allocated.          All of us at Capital Property Solutions look forward to continuing to work with you and your association.       Yours in community,     On behalf of Ramblewood Unit Owners' Association    This Community is Professionally Managed by:    Capital Property Solutions      portal.cpscolumbus.com      Payment Options Paying your Association Assessments just got easier! Capital    Property Solutions now offers multiple electronic payment options,  explore the choices below and pick what's right for you.        Recurring Payment:      Recurring Payment:      One-Time Payment        Total New Balance   Flat Rate       A fluctuating recurring payment A set amount paid       A non-recurring payment based on your account balance   at a recurring interval     setup directly by you   Always Current  Predictable Budgeting   Complete Control        Automatically pays the full     Know exactly how much is    Choose the exact amount and     balance due, even if it changes.        coming out each time.   timing of your payment. No Carrying Balances        Avoid Late Fees Great for Irregular     Helps prevent past-due  Automated payments reduce       Payments        amounts from piling up.     the risk of missing deadlines.  Pay only when payment is due.   Perfect for Variable Charges    Saves Time      Useful for Special          Ideal if your assessments       After setup, manual changes     Assessments or Catch-Ups        include water or fluctuating    are only needed if the amount       Flexible for covering unique    fees.   changes.        situations.     Worry-Free Compliance   No Commitment   Stays in sync with your account     No need to set up recurring     so your account is always up to payments.       date.   Hands-On Visibility     No surprise withdrawals     Recommended     Option  Owner Payment Info      Payments can be made over       Checks can be mailed to the phone by calling    For online payments you will need   the following information:      Western Alliance Bank   Western Alliance Bank   Management ID: 7106     (844)-739-2331      P.O. Box 93003  Association ID: RUOA    Las Vegas, NV 89193     Account Number: RUOA83458       Electronic Payments can be made/setup through Western Alliance Bank via your CPS    Homeowner's portal at: portal.cpscolumbus.com

Multi page read — Tables and Forms

If you wish to read only tables & forms from a multi-page document in S3, here’s how we can do it

aws textract start-document-analysis \
  --document-location '{"S3Object":{"Bucket":"textract-test-oh-dev-01","Name":"Budget_Letter_2027.pdf"}}' \
  --feature-types TABLES FORMS
# Execution results
{
    "JobId": "42582cf63fc4c0800f8eda8f439cb03d30be71ea578f96cecdc4e6c669d124cf"
}

We query on this Job ID for details

aws textract get-document-analysis --job-id 42582cf63fc4c0800f8eda8f439cb03d30be71ea578f96cecdc4e6c669d124cf
# Execution Results
{
    "DocumentMetadata": {
        "Pages": 2
    },
    "JobStatus": "SUCCEEDED",
    "Blocks": [
        {
            "BlockType": "PAGE",
            "Geometry": {
                "BoundingBox": {
                    "Width": 1.0,
                    "Height": 1.0,
                    "Left": 0.0,
                    "Top": 0.0
                },
                "Polygon": [
                    {
                        "X": 1.9625688310043188e-06,
                        "Y": 0.0
                    },
                    {
                        "X": 1.0,
                        "Y": 0.0
                    },
                    {
                        "X": 1.0,
                        "Y": 1.0
                    },
                    {
                        "X": 0.0,
                        "Y": 1.0
                    }
                ]

You can do the same from a simple re-usable python script

git clone
uv init .
uv add boto3
uv run read_textract.py 42582cf63fc4c0800f8eda8f439cb03d30be71ea578f96cecdc4e6c669d124cf
# Execution results
FORMS
  RE: -> 1975 Ramblebranch Dr
  This Community is Professionally Managed by: -> Capital Property Solutions portal.cpscolumbus.com
  Dear -> Krishnan Sriram Rama,
  Yours in community, -> On behalf of Ramblewood Unit Owners' Association
  October -> 02, 2026
  Krishnan Sriram Rama -> 1975 Ramblebranch Dr Columbus, OH 43220
  PO Box -> 630
  The Board of Directors of Ramblewood Unit Owners' Association approved the 2027 operating budget. Your 2027 assessment is $402.00, billed monthly beginning 01/01/2027. -> 
  One-Time Payment -> 
  Account Number: -> RUOA83458
  Association ID: -> RUOA
  Management ID: -> 7106
  Recurring Payment: -> 
  Homeowner's portal at: -> portal.cpscolumbus.com
  Recurring Payment: -> Flat Rate
  Payments can be made over the phone by calling Western Alliance Bank -> (844)-739-2331
  Checks can be mailed to -> Western Alliance Bank P.O. Box 93003 Las Vegas, NV 89193

TABLE 1 (page 2)
  Recurring Payment: Total New Balance | Recurring Payment: Flat Rate | One-Time Payment
  A fluctuating recurring payment based on your account balance | A set amount paid at a recurring interval | A non-recurring payment setup directly by you
  Always Current Automatically pays the full balance due, even if it changes. No Carrying Balances Helps prevent past-due amounts from piling up. Perfect for Variable Charges Ideal if your assessments include water or fluctuating fees. Worry-Free Compliance Stays in sync with your account so your account is always up to date. Recommended Option | Predictable Budgeting Know exactly how much is coming out each time. Avoid Late Fees Automated payments reduce the risk of missing deadlines. Saves Time After setup, manual changes are only needed if the amount changes. | Complete Control Choose the exact amount and timing of your payment. Great for Irregular Payments Pay only when payment is due. Useful for Special Assessments or Catch-Ups Flexible for covering unique situations. No Commitment No need to set up recurring payments. Hands-On Visibility No surprise withdrawals
  Owner Payment Info For online payments you will need the following information: Management ID: 7106 Association ID: RUOA Account Number: RUOA83458 | Payments can be made over the phone by calling Western Alliance Bank (844)-739-2331 | Checks can be mailed to Western Alliance Bank P.O. Box 93003 Las Vegas, NV 89193

Step 4: Delete the files and query again

Delete the PDF from S3

aws s3 rm s3://textract-test-oh-dev-01/Budget_Letter_2027.pdf
# Execution results
delete: s3://textract-test-oh-dev-01/Budget_Letter_2027.pdf

Extract details on PDF

aws textract detect-document-text \
  --document '{"S3Object":{"Bucket":"textract-test-oh-dev-01","Name":"Budget_Letter_2027.pdf"}}' \
  --query 'Blocks[?BlockType==`LINE`].Text' --output text
# Execution results
aws: [ERROR]: An error occurred (InvalidS3ObjectException) when calling the DetectDocumentText operation: Unable to get object metadata from S3. Check object key, region and/or access permissions.

This confirms that Textract keeps no copy of a document. It reads the object from S3 on every call, so once the file is gone the call fails.

The same error appears for a misspelled file name, a bucket in a different region from the call, or a caller without s3:GetObject. Check those three first when it shows up unexpectedly.

Results summary

1. Create bucket (console): bucket textract-test-oh-dev-01 created in us-east-2.
2. Upload Budget_Letter_2027.pdf (console): succeeded, 105.0 KB.
3. detect-document-text on Budget_Letter_2027.pdf: failed with UnsupportedDocumentException.
4. Upload textract_sample.pdf (aws s3 cp): succeeded.
5. detect-document-text on textract_sample.pdf: succeeded, full text returned with one character missed.
6. aws s3 rm on Budget_Letter_2027.pdf: deleted.
7. detect-document-text on textract_sample.pdf: succeeded, identical to item 5.
8. aws s3 rm on textract_sample.pdf: deleted.
9. detect-document-text on textract_sample.pdf: failed with InvalidS3ObjectException.

The bucket is now empty.

Automatic deletion of uploaded files

A lifecycle rule removes every object one day after upload:

aws s3api put-bucket-lifecycle-configuration \
  --bucket textract-test-oh-dev-01 \
  --lifecycle-configuration '{"Rules":[{"ID":"expire-after-1-day","Status":"Enabled","Filter":{},"Expiration":{"Days":1}}]}'

One day is the minimum. S3 rounds expiry to the next midnight UTC and deletes some time after that, so a file can live roughly 24 to 48 hours. A strict limit under 24 hours needs a scheduled job or a delete right after processing.

This is an introduction to textract. In our next piece we want to do all of this through automation with close to enterprise grade architecture.

We are just getting warmed up……

Press enter or click to view image in full size

Keep reading and stay safe!