A vendor sends over a year of delivery notes. It arrives as one PDF, several hundred pages, scanned on a machine that was clearly overdue for service. Someone asks how long it will take to get the reference numbers into the warehouse table, and the honest answer is that the OCR call is the easy part.<\/p>\n\n\n\n
Document pipelines are not hard because optical character recognition is inaccurate. Amazon Textract reads text well. They are hard because everything after the API call belongs to you, and because Textract almost never fails loudly. You get a 200 response, a list of blocks, a confidence score, and a record with an empty field where the purchase order number should have been. Nothing alerts. The row lands in the warehouse with a null, and someone in finance notices three weeks later while reconciling.<\/p>\n\n\n\n
That silent gap is the whole problem. Getting reliable Amazon Textract structured data out of files you did not design has less to do with OCR accuracy than with everything around it: which operation to call for which document family, why the response is a graph rather than a record, how to route on confidence instead of trusting it, and the limits that quietly truncate your data. All of it assumes documents you cannot ask anyone to change.<\/p>\n\n\n\n
Internal documents are generated by a template you control. External documents vary along three axes at once, and each one has its own failure mode:<\/p>\n\n\n\n
You cannot fix any of that upstream. You can only detect it at ingest and route accordingly. The sections below are organized by the failure family each one produces.<\/p>\n\n\n\n
Textract accepts JPEG, PNG, PDF, and TIFF. It does not support XFA-based PDFs, and it will not open a password-protected PDF. Images are accepted up to 10,000 pixels on any side. For PDFs, the maximum page dimensions are 40 inches and 9,000 points.<\/p>\n\n\n\n
Two more constraints catch people out. Text detection covers English, French, German, Italian, Portuguese, and Spanish, and several capabilities are narrower still: handwriting, invoices and receipts, identity documents, and Queries are English only. Vertical text, common in Japanese and Chinese documents, is not supported at all. Rotation is fine, including heavy in-plane rotation. Vertical writing direction is not.<\/p>\n\n\n\n
Build an ingest gate that checks encryption, page count, byte size, and dimensions before it spends an API call, and give each rejection a reason code a human can act on. Then catch exceptions properly instead of wrapping the call in a bare retry. This is the one that silently eats data, so it goes early.<\/p>\n\n\n\n The synchronous operations, The asynchronous operations are a different shape. PDF and TIFF go up to 500 MB and 3,000 pages, while JPEG and PNG stay at 10 MB. You start a job, Textract works in the background, and you collect results by job ID.<\/p>\n\n\n\n A synchronous call looks like this. The document lives in S3, and you name the features you want:<\/p>\n\n\n\n The asynchronous version returns a job identifier immediately and publishes completion to an SNS topic. That is what you want in production, because polling a job inside a Lambda function means paying for a function that sleeps:<\/p>\n\n\n\n Results come back paginated, and forgetting the continuation token is a second, quieter way to lose most of a file:<\/p>\n\n\n\n Check Textract does not return fields. It returns a flat list of For form data, the shape is specific. A key-value pair is two blocks of type Two things about that snippet. The Tables follow the same pattern with different block types, and cells carry row and column indices plus span values for merged cells. Layout adds another set, including title, header, footer, section header, page number, list, and figure blocks, and it sequences text into human reading order. That last property is why Layout is worth requesting when the output is headed for a language model rather than a database: chunking on reading order beats chunking on raw line order.<\/p>\n\n\n\n Before hand-rolling any of this, look at the AWS-maintained parsers. The Textract is a family of operations, not one endpoint, and the biggest single accuracy win available is usually picking a narrower one. Features are billed per page and they stack, so requesting FORMS gives you whatever labels the document happens to contain. That means your downstream schema is hostage to a vendor’s wording. When they change “P.O. No.” to “Order Reference”, your parser looks for a key that no longer exists and writes a null.<\/p>\n\n\n\n Queries inverts this. You supply the question and an alias, and the alias comes back attached to the answer, so your output key is fixed by you rather than by the document:<\/p>\n\n\n\n The alias is the entire point. It is a contract between your schema and the extraction layer that survives a vendor redesign. There are ceilings: 15 queries per page synchronously, 30 per page asynchronously, English only. Phrase questions using words that actually appear on the page, and add positional hints when you know the layout, because the model uses them. If Queries underperforms on your corpus, adapters let you tune the feature against your own examples and pass an adapter ID and version at call time.<\/p>\n\n\n\n For invoices and receipts, reach for AnalyzeExpense first. Its response is shaped around the domain rather than around the page: each That optional label is the thing to notice. AnalyzeExpense can identify a vendor name printed only inside a logo, and pull line items out of a grid with no column headers. FORMS structurally cannot do either, because FORMS needs a key to exist. On receipts that is not a small accuracy delta, it is the difference between a usable field and an empty one.<\/p>\n\n\n\n Every extracted element carries a confidence score. Two mistakes follow from that.<\/p>\n\n\n\n The first is averaging into a document-level score. A document where every field is strong except the invoice total is not a mostly-good document. It is a document with one field that must not be trusted, surrounded by noise. Score fields, not documents.<\/p>\n\n\n\n The second is treating one threshold as universal. A misread address on a delivery note is an annoyance. A misread bank account number is an incident. Set thresholds per field from the cost of being wrong, then route into three lanes:<\/p>\n\n\n\n Validation rules do more work than thresholds here. A total that does not equal the sum of its line items is wrong at any confidence. Check-digit rules on account and tax identifiers catch character-level errors the model was perfectly confident about. Confidence tells you how sure the model is. Validation tells you whether the answer is even possible.<\/p>\n\n\n\n Textract can hand low-confidence results to Amazon Augmented AI through a human loop configuration on the API call, which saves building a review queue. Whether that beats a small internal tool depends on how much domain context your reviewers need on screen. Either way, capture the corrections. Reviewer edits are the only labeled data you get for free, and they are how you calibrate thresholds against your own corpus instead of guessing.<\/p>\n\n\n\n Textract bills per page, per feature. Your parser, meanwhile, will change repeatedly in the first months of a pipeline’s life, because that is what parsers do.<\/p>\n\n\n\n So separate extraction from parsing, permanently. Write the raw response JSON to S3 keyed by a hash of the document bytes plus the operation and feature set requested, then parse from that stored artifact. Reprocessing becomes free, deterministic, and diffable: you can replay a parser change across the whole back catalogue and compare outputs before promoting it. Without that cache, every parser bug fix is a bill.<\/p>\n\n\n\n Hashing content rather than filename also deduplicates the same scan arriving twice under different names, which happens constantly with email-driven intake. For the asynchronous operations, a client request token gives idempotency at the job level; reusing a token with different parameters raises a mismatch error rather than quietly starting a second job.<\/p>\n\n\n\n One caveat: source documents often contain personal data, so a cache is a retention decision. Set S3 lifecycle rules on both the originals and the raw JSON, and if working copies land on a workstation or a build box, delete them properly. Tools like O&O SafeErase exist for exactly that gap between “moved to trash” and “actually gone”.<\/p>\n\n\n\n Being fair about this matters, because AWS now offers overlapping paths to the same outcome. Amazon Bedrock Data Automation is a managed document processing service that handles classification and extraction behind one API, priced per document rather than per page and per feature. AWS positions it as the default starting point for new builds, and for mixed document types with no dominant format that recommendation is sound. You write far less orchestration.<\/p>\n\n\n\n Textract keeps the advantage where the corpus is high volume and standardized, where geometry and per-field confidence are needed for auditability, where regional availability constrains you, or where you want extraction to be deterministic and separately testable. Bounding boxes and confidence scores are not a nice-to-have in a regulated workflow, they are the evidence trail.<\/p>\n\n\n\n The hybrid is common and sensible: Textract for extraction, a Bedrock model for reasoning over the extracted text. Just do not send a multimodal model a full-page image because OCR felt inconvenient. It costs considerably more per page and gives you no geometry.<\/p>\n\n\n\n Yes, but only through the asynchronous operations. Synchronous calls accept a single page for PDF and TIFF input. Asynchronous processing handles PDF and TIFF up to 500 MB and 3,000 pages.<\/p>\n\n\n\n FORMS returns whatever key-value pairs it finds from labels printed on the page, so your output keys follow the document. Queries lets you ask for values by natural language question and attach your own alias to each answer, so output keys stay fixed when the layout changes. For a schema you must keep stable, Queries is the safer contract.<\/p>\n\n\n\n Billing is per page and varies by operation and feature, and requesting several features on one page adds their costs together. Check the current rate card for your region and multiply by pages, not documents. The practical lever is routing: send each document to the narrowest operation that answers your question, and cache raw responses so parser iteration is free.<\/p>\n\n\n\n It detects handwritten text, in English only. Treat handwritten fields as a separate confidence tier with lower auto-accept thresholds, because the variance across writers is much wider than for printed text.<\/p>\n\n\n\n Text detection covers English, French, German, Italian, Portuguese, and Spanish. Handwriting, invoices and receipts, identity documents, and Queries are English only. Vertically written text is not supported.<\/p>\n\n\n\n Bedrock Data Automation is the lower-effort default for mixed document types, with classification and extraction behind a single managed API. Textract fits better at high volume on standardized documents, where per-field confidence and geometry matter for audit, or where extraction needs to be deterministic and independently testable. Combining them is normal.<\/p>\n\n\n\n If one thing survives this post, make it this: Amazon Textract structured data extraction fails quietly, not loudly. The API returns success while your record is missing its most important field, because a synchronous call read one page of forty, or because a vendor renamed a label, or because a value came back at low confidence and nothing was watching.<\/p>\n\n\n\n So build for the silence. Gate at ingest, use asynchronous operations by default, pick the narrowest API per document family, pin your schema with query aliases, store the raw response, and route on per-field confidence backed by validation rules that know what a possible answer looks like. Do that and the OCR really does become the easy part.<\/p>\n\n\n\n Most of the difficulty in document extraction shows up after the proof of concept, once real intake replaces the sample files. That is the part I work on:<\/p>\n\n\n\n If you have a pipeline misbehaving, send me a sample document with the fields you need and the raw Textract JSON it produced. That is usually enough to see where it is going wrong.<\/p>\n\n\n\nBadDocumentException<\/code> means Textract could not read the file, and retrying fails identically. DocumentTooLargeException<\/code> means route to the asynchronous path or split the file. InvalidS3ObjectException<\/code> is usually IAM or a bucket-region mismatch, not a document problem. Only InternalServerErrorException<\/code> deserves a retry with backoff.<\/p>\n\n\n\nFailure family two: synchronous versus asynchronous is a correctness gate<\/h2>\n\n\n\n
DetectDocumentText<\/code> and AnalyzeDocument<\/code>, cap at 10 MB in memory. For PDF and TIFF input they also cap at one page<\/strong>. Not one page per call with automatic paging. One page, full stop. Hand a synchronous call a 40-page PDF and you get page one, and a pipeline that reports success.<\/p>\n\n\n\naws textract analyze-document \n --document '{\"S3Object\":{\"Bucket\":\"my-doc-bucket\",\"Name\":\"inbound\/note-0042.png\"}}' \n --feature-types '[\"FORMS\",\"TABLES\"]' \n --region us-east-1<\/code><\/pre>\n\n\n\nimport boto3\n\ntextract = boto3.client(\"textract\")\n\nstart = textract.start_document_analysis(\n DocumentLocation={\n \"S3Object\": {\"Bucket\": \"my-doc-bucket\", \"Name\": \"inbound\/batch-0042.pdf\"}\n },\n FeatureTypes=[\"FORMS\", \"TABLES\"],\n NotificationChannel={\n \"SNSTopicArn\": \"arn:aws:sns:us-east-1:111122223333:textract-jobs\",\n \"RoleArn\": \"arn:aws:iam::111122223333:role\/TextractSnsPublishRole\",\n },\n)\n\njob_id = start[\"JobId\"]<\/code><\/pre>\n\n\n\nblocks = []\nnext_token = None\n\nwhile True:\n kwargs = {\"JobId\": job_id}\n if next_token:\n kwargs[\"NextToken\"] = next_token\n\n page = textract.get_document_analysis(**kwargs)\n blocks.extend(page[\"Blocks\"])\n\n next_token = page.get(\"NextToken\")\n if not next_token:\n break<\/code><\/pre>\n\n\n\nJobStatus<\/code> before you trust Blocks<\/code>. A job can come back partially successful, which means some pages processed and some did not. If you treat that as success you will publish a document that is missing its middle.<\/p>\n\n\n\nFailure family three: the response is a graph, not a record<\/h2>\n\n\n\n
Block<\/code> objects, each with an ID and relationships pointing at other IDs. Reassembling those into a row is your code, and it is where most of the real work lives.<\/p>\n\n\n\nKEY_VALUE_SET<\/code>, distinguished by their EntityTypes<\/code> array containing either KEY<\/code> or VALUE<\/code>. The key block carries a relationship of type VALUE<\/code> holding the ID of its value block, and a relationship of type CHILD<\/code> holding the IDs of the WORD<\/code> blocks that spell out the label. The value block carries only CHILD<\/code> relationships pointing at its own words. So reading one field means three hops.<\/p>\n\n\n\nblocks_by_id = {b[\"Id\"]: b for b in blocks}\n\ndef child_text(block):\n parts = []\n for rel in block.get(\"Relationships\", []):\n if rel[\"Type\"] != \"CHILD\":\n continue\n for cid in rel[\"Ids\"]:\n child = blocks_by_id[cid]\n if child[\"BlockType\"] == \"WORD\":\n parts.append(child[\"Text\"])\n elif child[\"BlockType\"] == \"SELECTION_ELEMENT\":\n parts.append(child[\"SelectionStatus\"])\n return \" \".join(parts)\n\nfields = {}\nfor b in blocks:\n if b[\"BlockType\"] != \"KEY_VALUE_SET\":\n continue\n if \"KEY\" not in b.get(\"EntityTypes\", []):\n continue\n\n value_text = \"\"\n for rel in b.get(\"Relationships\", []):\n if rel[\"Type\"] == \"VALUE\":\n for vid in rel[\"Ids\"]:\n value_text = child_text(blocks_by_id[vid])\n\n fields[child_text(b)] = (value_text, b[\"Confidence\"])<\/code><\/pre>\n\n\n\nSELECTION_ELEMENT<\/code> branch matters because checkboxes and radio buttons are values too, and their content is a selection status rather than text. And the confidence on the key block is not a separate key confidence: Textract returns the same value for both halves of a pair. If you planned to compare label confidence against value confidence to catch mismatches, that signal does not exist.<\/p>\n\n\n\namazon-textract-response-parser<\/code> package and the higher-level amazon-textract-textractor<\/code> library both turn the block graph into objects with sensible properties. Writing your own traversal is a good way to understand the model and a poor way to spend two sprints.<\/p>\n\n\n\nGetting Amazon Textract structured data out of the right API<\/h2>\n\n\n\n
TABLES<\/code> on a corpus with no tables costs money and returns noise.<\/p>\n\n\n\n\n
Why Queries beats FORMS on documents you don’t control<\/h3>\n\n\n\n
aws textract analyze-document \n --document '{\"S3Object\":{\"Bucket\":\"my-doc-bucket\",\"Name\":\"inbound\/note-0042.png\"}}' \n --feature-types '[\"QUERIES\"]' \n --queries-config '{\"Queries\":[\n {\"Text\":\"What is the purchase order number?\",\"Alias\":\"PO_NUMBER\"},\n {\"Text\":\"What is the delivery date?\",\"Alias\":\"DELIVERY_DATE\"}\n ]}' \n --region us-east-1<\/code><\/pre>\n\n\n\nInvoices are their own problem<\/h3>\n\n\n\n
ExpenseDocument<\/code> holds SummaryFields<\/code> for header-level data and LineItemGroups<\/code> containing the line items. Fields carry a normalized Type<\/code> such as VENDOR_NAME<\/code>, plus a ValueDetection<\/code> and an optional LabelDetection<\/code>.<\/p>\n\n\n\nFailure family four: confidence is per field and it is not your risk model<\/h2>\n\n\n\n
\n
Failure family five: reprocessing you didn’t budget for<\/h2>\n\n\n\n
import hashlib\n\ndigest = hashlib.sha256(doc_bytes).hexdigest()\nfeatures = \"-\".join(sorted([\"FORMS\", \"TABLES\"]))\nkey = f\"textract-raw\/{digest}\/analyze-document\/{features}.json\"<\/code><\/pre>\n\n\n\nWhere Textract stops being the right tool<\/h2>\n\n\n\n
Troubleshooting<\/h2>\n\n\n\n
\n
Common mistakes<\/h2>\n\n\n\n
\n
Best practices<\/h2>\n\n\n\n
\n
Frequently asked questions<\/h2>\n\n\n\n
Can Amazon Textract process multi-page PDFs?<\/h3>\n\n\n\n
What is the difference between FORMS and Queries?<\/h3>\n\n\n\n
How much does Amazon Textract cost?<\/h3>\n\n\n\n
Does Textract handle handwriting?<\/h3>\n\n\n\n
Which languages does Amazon Textract support?<\/h3>\n\n\n\n
Should I use Textract or Bedrock Data Automation?<\/h3>\n\n\n\n
\n\n\n\nConclusion<\/h2>\n\n\n\n
Need help turning documents into a pipeline you can trust?<\/h2>\n\n\n\n
\n