Structured data extraction with Claude: invoice, receipt, and form processing at scale

Most developers underestimate how hard reliable structured data extraction with Claude actually is in production. Getting Claude to return JSON from a single clean invoice in a demo is trivial. Getting it to return consistent, validated, schema-compliant JSON from 10,000 invoices — including scanned PDFs, handwritten receipts, multi-page purchase orders, and forms with merged cells — is a completely different engineering problem.

This article covers the three main approaches (prompt engineering, tool use, and schema-constrained output), benchmarks them against real documents, gives you working code for each, and tells you exactly which one to reach for depending on your pipeline’s tolerance for errors.

Why “Just Ask for JSON” Breaks in Production

The naive approach — “return your answer as JSON” in the system prompt — works maybe 85-90% of the time on clean digital documents. That sounds fine until you’re running 5,000 documents a day and getting 500-750 malformed responses that crash your downstream pipeline. Common failure modes:

• Trailing commas in JSON arrays (Claude occasionally generates them, Python’s json.loads rejects them)
• Markdown fences wrapping the JSON (```json\n{...}\n```) even when you explicitly told it not to
• Extra explanation text before or after the JSON block
• Schema drift — field names that vary slightly across runs (“invoice_number” vs “invoiceNumber” vs “invoice_no”)
• Missing nullable fields — if a field isn’t present in the document, Claude sometimes omits the key entirely rather than returning null

These aren’t model bugs you can complain to Anthropic about. They’re the expected behavior of a language model that’s optimizing for natural language coherence, not JSON spec compliance. The fix is choosing the right extraction architecture from the start.

The Three Approaches: Architecture Overview

1. Prompt Engineering (System Prompt + Output Parsing)

Force JSON output via the system prompt plus a strict output parser with retry logic. This is the cheapest approach — you’re paying only for the extraction tokens, no overhead.

import anthropic
import json
import re
from pydantic import BaseModel, ValidationError
from typing import Optional

client = anthropic.Anthropic()

SYSTEM_PROMPT = """You are a document data extraction engine.
Return ONLY valid JSON matching the schema below. No markdown, no explanation, no preamble.
If a field is not present in the document, return null for that field.

Schema:
{
  "invoice_number": "string or null",
  "invoice_date": "ISO 8601 date string or null",
  "vendor_name": "string or null",
  "vendor_address": "string or null",
  "line_items": [{"description": "string", "quantity": "number", "unit_price": "number", "total": "number"}],
  "subtotal": "number or null",
  "tax_amount": "number or null",
  "total_amount": "number or null",
  "currency": "3-letter ISO code or null",
  "payment_terms": "string or null"
}"""

def extract_invoice(document_text: str, max_retries: int = 2) -> dict:
    for attempt in range(max_retries + 1):
        response = client.messages.create(
            model="claude-haiku-4-5",  # Haiku is fast and cheap for extraction
            max_tokens=1024,
            system=SYSTEM_PROMPT,
            messages=[{"role": "user", "content": f"Extract data from this document:\n\n{document_text}"}]
        )
        
        raw = response.content[0].text.strip()
        
        # Strip markdown fences if Claude added them anyway
        raw = re.sub(r'^```(?:json)?\n?', '', raw)
        raw = re.sub(r'\n?```$', '', raw)
        
        try:
            return json.loads(raw)
        except json.JSONDecodeError as e:
            if attempt == max_retries:
                raise ValueError(f"Failed to parse JSON after {max_retries + 1} attempts: {e}")
            # On retry, add the failed output to context so Claude can self-correct
            continue
    

Cost at Claude Haiku pricing (~$0.80/M input, $4/M output): A typical invoice extraction with a 500-token document and 300-token output costs roughly $0.0016 per document. At 10,000 documents/day, that’s $16/day — well within budget for most use cases.

2. Tool Use (Function Calling)

Define your target schema as a tool definition. Claude is forced to call the tool with arguments that match your parameter spec — this is structurally more reliable than asking for raw JSON because the API enforces that a tool call is made.

tools = [
    {
        "name": "extract_invoice_data",
        "description": "Extract structured invoice data from a document",
        "input_schema": {
            "type": "object",
            "properties": {
                "invoice_number": {"type": ["string", "null"], "description": "Invoice or reference number"},
                "invoice_date": {"type": ["string", "null"], "description": "Invoice date in ISO 8601"},
                "vendor_name": {"type": ["string", "null"]},
                "vendor_address": {"type": ["string", "null"]},
                "line_items": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
                            "description": {"type": "string"},
                            "quantity": {"type": "number"},
                            "unit_price": {"type": "number"},
                            "total": {"type": "number"}
                        },
                        "required": ["description", "total"]
                    }
                },
                "total_amount": {"type": ["number", "null"]},
                "currency": {"type": ["string", "null"]},
                "tax_amount": {"type": ["number", "null"]}
            },
            "required": ["invoice_number", "vendor_name", "total_amount"]
        }
    }
]

def extract_with_tools(document_text: str) -> dict:
    response = client.messages.create(
        model="claude-haiku-4-5",
        max_tokens=1024,
        tools=tools,
        tool_choice={"type": "any"},  # Force tool use — don't let Claude respond in text
        messages=[{"role": "user", "content": f"Extract invoice data:\n\n{document_text}"}]
    )
    
    # Tool use blocks are always valid JSON — no parsing needed
    for block in response.content:
        if block.type == "tool_use" and block.name == "extract_invoice_data":
            return block.input  # Already a Python dict
    
    raise ValueError("No tool call in response")

The tool_choice: {"type": "any"} parameter is critical — without it, Claude may decide to respond in text instead of calling the tool. This is the most common gotcha I see developers miss when first implementing tool-based extraction.

3. Vision-Based Extraction (PDF and Image Input)

For scanned documents, PDFs, and images, you pass the document as a base64-encoded image. Claude Sonnet and Haiku both support vision input. This is where structured data extraction with Claude really earns its keep over OCR pipelines — you skip the OCR error-correction step entirely.

import base64
from pathlib import Path

def extract_from_image(image_path: str) -> dict:
    image_data = base64.standard_b64encode(Path(image_path).read_bytes()).decode("utf-8")
    
    # Determine media type
    suffix = Path(image_path).suffix.lower()
    media_type_map = {".jpg": "image/jpeg", ".jpeg": "image/jpeg", 
                      ".png": "image/png", ".pdf": "application/pdf"}
    media_type = media_type_map.get(suffix, "image/jpeg")
    
    response = client.messages.create(
        model="claude-sonnet-4-5",  # Use Sonnet for vision — Haiku's accuracy on complex layouts drops
        max_tokens=1024,
        tools=tools,
        tool_choice={"type": "any"},
        messages=[{
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {"type": "base64", "media_type": media_type, "data": image_data}
                },
                {"type": "text", "text": "Extract all invoice data from this document."}
            ]
        }]
    )
    
    for block in response.content:
        if block.type == "tool_use":
            return block.input
    raise ValueError("No tool call returned")

Benchmark: Accuracy Across 200 Real Documents

I ran all three approaches against a test set of 200 documents: 80 digital invoices (PDF text layer), 60 scanned receipts (image), and 60 multi-page HTML forms. Here’s what I found:

Key insight: Tool use’s 10x improvement in parse success rate over prompt engineering costs you maybe 12% more per run. That’s almost always worth it. The jump to Sonnet with vision is where the economics change significantly — only go there if you’re working with actual images or your accuracy requirements are strict (e.g., healthcare, finance, legal).

For teams processing documents at scale, the batch API dramatically changes the math. You can hit 50% cost reduction by shifting non-urgent workloads to Claude’s batch processing API, which is purpose-built for exactly this kind of high-volume extraction pipeline.

Handling the Hard Cases

Multi-Currency and International Formats

European invoices use comma as decimal separator. Japanese receipts might not have line items at all. Your schema needs to handle this gracefully rather than relying on Claude to normalize everything correctly. Include explicit instructions: “Return all numbers as floats using period as decimal separator, regardless of the source document format.”

Multi-Page Documents

Claude’s context window handles multi-page text fine, but for image-based extraction, you’ll need to either: (a) extract each page separately and merge results, or (b) use a PDF-to-text step for non-scanned documents and fall back to vision only for scanned pages. I prefer option (b) because it keeps vision API costs down on the majority of modern invoices which have selectable text.

import pymupdf  # pip install pymupdf

def extract_pdf_smart(pdf_path: str) -> dict:
    """Use text extraction when possible, fall back to vision for image-only pages."""
    doc = pymupdf.open(pdf_path)
    
    text_pages = []
    image_pages = []
    
    for page_num, page in enumerate(doc):
        text = page.get_text().strip()
        if len(text) > 50:  # Threshold for "has meaningful text"
            text_pages.append(text)
        else:
            # Render page as image for vision processing
            mat = pymupdf.Matrix(2, 2)  # 2x scale for better OCR accuracy
            pix = page.get_pixmap(matrix=mat)
            image_pages.append((page_num, pix.tobytes("png")))
    
    if text_pages and not image_pages:
        # Pure digital PDF — use cheap text extraction
        return extract_with_tools("\n\n--- PAGE BREAK ---\n\n".join(text_pages))
    elif image_pages:
        # Has scanned pages — use vision for those, merge with text
        # (implementation depends on your merge strategy)
        return extract_from_image(pdf_path)
    
    raise ValueError("Empty PDF")

Validation After Extraction

Never trust extracted numbers without a sanity check. Line item totals should sum to subtotal; subtotal plus tax should equal total. Build this into your pipeline rather than assuming Claude’s arithmetic is correct — it usually is, but “usually” isn’t production-grade.

def validate_invoice(data: dict) -> tuple[bool, list[str]]:
    errors = []
    
    if data.get("line_items") and data.get("subtotal"):
        computed_subtotal = sum(item.get("total", 0) for item in data["line_items"])
        if abs(computed_subtotal - data["subtotal"]) > 0.02:  # Allow 2 cent rounding tolerance
            errors.append(f"Line item sum {computed_subtotal} doesn't match subtotal {data['subtotal']}")
    
    if data.get("subtotal") and data.get("tax_amount") and data.get("total_amount"):
        expected_total = data["subtotal"] + data["tax_amount"]
        if abs(expected_total - data["total_amount"]) > 0.02:
            errors.append(f"Subtotal + tax {expected_total} doesn't match total {data['total_amount']}")
    
    return len(errors) == 0, errors

For production pipelines where correctness failures are costly, pair this with the patterns in our guide on getting consistent JSON output from Claude without hallucinations — it goes deeper on schema design and self-correction loops.

Three Misconceptions That’ll Burn You

Misconception 1: Claude Sonnet is always better than Haiku for extraction. Not true for structured data tasks. On clean digital invoices, Haiku’s field accuracy is within 2-3% of Sonnet at roughly 10x lower cost. Use Sonnet only when document quality is poor or layouts are genuinely complex.

Misconception 2: Vision mode handles PDFs natively. The Anthropic API accepts image formats (JPEG, PNG, GIF, WebP). For PDFs, you need to convert pages to images first, or use the document content source type. Don’t assume PDF → vision just works without the conversion step.

Misconception 3: Higher temperature means more creative/flexible extraction. For extraction tasks, set temperature to 0. Extraction is deterministic by definition — you want the same field from the same document to return the same value every time. If you’re seeing variable output, temperature isn’t the lever to pull; your schema or prompts need fixing. We cover this in detail in the temperature and top-P guide.

Deploying at Scale: Concurrency and Cost Management

If you’re processing thousands of documents, you need to handle rate limits and parallelize intelligently. Claude’s API rate limits are per-minute, so a simple async queue with a semaphore works well:

import asyncio
import anthropic
from typing import List

async def process_batch(documents: List[str], concurrency: int = 10) -> List[dict]:
    client = anthropic.AsyncAnthropic()
    semaphore = asyncio.Semaphore(concurrency)
    
    async def process_one(doc: str) -> dict:
        async with semaphore:
            response = await client.messages.create(
                model="claude-haiku-4-5",
                max_tokens=1024,
                tools=tools,
                tool_choice={"type": "any"},
                messages=[{"role": "user", "content": f"Extract invoice data:\n\n{doc}"}]
            )
            for block in response.content:
                if block.type == "tool_use":
                    return block.input
            return {}
    
    return await asyncio.gather(*[process_one(doc) for doc in documents])

For sustained high-volume workloads, the LLM caching strategies guide has a good breakdown of where prompt caching helps on extraction workloads — the system prompt is cacheable and on a 10K document run, that cache hit alone can reduce costs by 20-30%.

Also worth checking your deployment architecture. If you’re running extraction as a serverless function, the cold start behavior and timeout limits vary significantly by platform — our serverless platform comparison for Claude agents covers the practical tradeoffs between Vercel, Replicate, and Beam for exactly this kind of workload.

Bottom Line: Which Approach for Which Situation

Solo founder or early-stage product: Start with tool use + Haiku. It’s cheap (~$1.80/1K docs), reliable (99%+ parse success), and the schema doubles as your documentation. Add validation logic for numeric fields. Skip vision unless your input is actually scanned images.

High-volume pipeline (100K+ docs/month): Tool use + Haiku for digital documents, Sonnet vision only for confirmed scanned inputs. Route with the PyMuPDF text-detection approach above. Use async batching with semaphores and enable prompt caching on your system prompt. At 100K docs/month with Haiku, you’re looking at roughly $180/month — very manageable.

Enterprise / regulated industries: Add a validation layer (arithmetic checks, schema validation with Pydantic, human-review routing for confidence-flagged extractions). Consider a two-pass approach: Haiku does the extraction, a lightweight rule check flags anomalies, Sonnet re-processes only the flagged documents. This keeps costs near Haiku rates while getting Sonnet accuracy where it matters.

Structured data extraction with Claude is genuinely production-ready today — the tool use approach is reliable enough to build a business on. The failure modes are predictable, the costs are manageable, and the vision capability removes the need for a separate OCR vendor in most cases. The engineering challenge is in the validation and routing layer, not the extraction itself.