How to extract invoice data from PDFs into structured JSON

Invoice PDFs are structurally unpredictable. Vendor A ships a five-column line-item table, vendor B embeds the same information in a paragraph block, and half the scanned copies in a legacy archive have no text layer at all. Generic text extraction reads characters in the order they were written to the file rather than the reading order a human sees, so field values drift with every layout variation.

The Foxit PDF Structural Extraction API addresses this directly. You submit a PDF invoice and receive a typed, hierarchical JSON document with named element types, bounding regions, and an addressable table cell grid. This guide covers the four REST calls that turn a raw PDF into a StructureInfo.json file, the Python post-processing that maps that output onto a clean invoice schema, and the edge cases your pipeline will hit on real vendor documents. Every response shape and field name below comes from a live run against the API, not from the reference docs alone.

Why invoice PDFs break generic parsers

Three structural problems cause most invoice parsing failures, and OCR accuracy is only one of them.

The first is layout variance across vendors. A PDF's text layer records characters in the order they were drawn, which often follows vector rendering order rather than left-to-right, top-to-bottom reading order. Extract raw text from a five-column line-item table and you frequently get interleaved fragments, where description text from one column mixes with unit prices from another because the writer rendered all rows of one column before moving to the next. No string-parsing logic reliably recovers column boundaries from that flattened sequence.

The second is merged and multi-row cells. Line-item tables routinely span cells across rows for items with multi-line descriptions. Text extraction collapses those cell boundaries into a flat string and drops the row-to-total relationship an accounting system needs.

The third is rasterized scans with no text layer. A PDF created by scanning a paper invoice contains only an embedded image, so anything that reads the text layer alone comes back empty. Adobe's own Acrobat documentation puts it plainly, noting that a scanned file "contains only image data, not searchable text." Tools built for scanned input bundle an OCR step rather than skipping it, and any pipeline you build has to do the same before extraction can happen.

Structure-aware extraction addresses all three by classifying document regions into typed elements before exposing their content.

Invoice fields to target before touching the API

Define the target schema before writing code. A concrete target tells you which elements to read from StructureInfo.json and which to skip, which saves iteration time on every invoice you process.

A workable invoice schema covers three groups:

• Header fields, including vendor name, invoice number, invoice date, due date, and payment terms
• Line items, a repeating array of description, quantity, unit price, and line total
• Footer totals, including subtotal, tax amount, and total amount due

{
  "vendor_name": "",
  "invoice_number": "",
  "invoice_date": "",
  "due_date": "",
  "payment_terms": "",
  "line_items": [
    {
      "description": "",
      "quantity": "",
      "unit_price": "",
      "line_total": ""
    }
  ],
  "subtotal": "",
  "tax": "",
  "total_due": ""
}

Keep every value a string at extraction time. Type conversion, currency parsing, and date normalization belong downstream, after validation, where a bad value can be rejected with context instead of raising inside the parser.

The sample invoice used throughout this guide is invoice_full_test.pdf, so you can run every call below against the same document.

The input document. Notice that the Subtotal, Tax Rate, Tax Amount, and Total Due labels sit in the second-to-last column rather than the first. That detail determines how the post-processing code has to find them.

Prerequisites

You need the following before the first API call:

• Python 3.9 or newer and pip
• A virtual environment via venv, so the dependency below stays isolated
• The requests library for HTTP calls
• A code editor such as VS Code with the Python extension
• A free Foxit developer account

Scaffold the workspace in one shot:

mkdir invoice-extraction && cd invoice-extraction && python3 -m venv .venv && source .venv/bin/activate && pip install requests

Then download the sample invoice into that folder:

curl -L -o invoice_full_test.pdf https://github.com/lucienchemaly/foxit-demo-templates/raw/main/invoice_full_test.pdf

Foxit API authentication and setup

Signing up activates a free Developer plan that includes 500 credits per year with no credit card required. A structural extraction call costs one credit, while the upload, polling, and download calls are not billed, so a full run of the workflow below costs a single credit.

The account creation screen. The free Developer plan is enough to work through this entire guide.

Foxit authenticates PDF Services requests with a client ID and client secret passed as HTTP headers, so there is no OAuth token exchange to implement. Both values come from the default application created in your Developer Portal dashboard, alongside the base URL your calls need.

The credentials panel. Copy the Client ID and Client Secret into environment variables rather than pasting them into source files.

Export them into your shell so no credential is ever committed:

export FOXIT_CLIENT_ID="your_client_id"
export FOXIT_CLIENT_SECRET="your_client_secret"

The structural extraction reference page carries a Test Request button that fires live calls straight from the browser, which is the quickest way to confirm your credentials work before writing any Python. The endpoint is currently labelled Trial in the reference, so expect its surface to evolve.

Pin your parser to the version field inside the analyzeResult response. The current schema ships as 1.0.7, and pinning prevents silent breakage if that changes.

The four-step PDF to JSON invoice extraction workflow

The API is asynchronous. You upload a document, start a task, poll until the task completes, then download the result.

All four paths sit under https://na1.fusion.foxit.com/pdf-services. Calling them without that prefix returns 404.

The path prefix matters more than it looks. The four endpoints live under /pdf-services/api/..., and requesting a bare /documents/{id}/download returns 404 rather than a helpful error.

import io
import json
import os
import time
import zipfile

import requests

BASE_URL = "https://na1.fusion.foxit.com/pdf-services"
HEADERS = {
    "client_id": os.environ["FOXIT_CLIENT_ID"],
    "client_secret": os.environ["FOXIT_CLIENT_SECRET"],
}
POLL_SECONDS = 2
POLL_TIMEOUT = 120


def extract_structure(pdf_path: str) -> dict:
    # Step 1: upload the PDF (multipart/form-data, 100 MB maximum)
    with open(pdf_path, "rb") as handle:
        upload = requests.post(
            f"{BASE_URL}/api/documents/upload",
            headers=HEADERS,
            files={"file": (os.path.basename(pdf_path), handle, "application/pdf")},
        )
    upload.raise_for_status()
    document_id = upload.json()["documentId"]

    # Step 2: start the structural extraction task
    started = requests.post(
        f"{BASE_URL}/api/documents/pdf-structural-extract",
        headers=HEADERS,
        json={"documentId": document_id},
    )
    started.raise_for_status()
    task_id = started.json()["taskId"]

    # Step 3: poll until COMPLETED, bounded, and handle FAILED
    deadline = time.monotonic() + POLL_TIMEOUT
    while True:
        response = requests.get(f"{BASE_URL}/api/tasks/{task_id}", headers=HEADERS)
        response.raise_for_status()
        task = response.json()
        if task["status"] == "COMPLETED":
            break
        if task["status"] == "FAILED":
            raise RuntimeError(f"extraction task {task_id} FAILED: {task}")
        if time.monotonic() > deadline:
            raise TimeoutError(f"task {task_id} stuck at {task['status']}")
        time.sleep(POLL_SECONDS)

    # Step 4: download the result ZIP and read StructureInfo.json
    result = requests.get(
        f"{BASE_URL}/api/documents/{task['resultDocumentId']}/download",
        headers=HEADERS,
    )
    result.raise_for_status()
    with zipfile.ZipFile(io.BytesIO(result.content)) as archive:
        return json.loads(archive.read("StructureInfo.json"))

In this code, you read both credentials from the environment, upload the PDF as multipart form data and capture the returned documentId, hand that id to the extraction endpoint to receive a taskId, then poll the task endpoint every two seconds. The loop is bounded by a deadline and checks explicitly for FAILED, so a rejected document raises instead of spinning forever. Once the status reads COMPLETED, the task payload carries a resultDocumentId, which you exchange for a ZIP archive and read StructureInfo.json out of in memory.

Status values are uppercase (PENDING, IN_PROGRESS, COMPLETED, FAILED), and there is no synchronous variant of this endpoint. The download returns application/zip containing StructureInfo.json plus one PNG for each detected table region.

A real run against the sample invoice. The task reports IN_PROGRESS at 20 percent before reaching COMPLETED, and the final object carries every field from the schema defined earlier.

How to map raw output to a clean invoice schema

Choosing an invoice data extraction API is only half the work. The other half is mapping whatever it returns onto a schema your backend already understands, and that mapping is where the shape of the response starts to matter.

StructureInfo.json wraps everything in an analyzeResult object with four top-level keys, version, pages, info, and elements. The elements array is where the work happens. Each element carries a type drawn from twelve values, including paragraph, table, title, image, form, and formula, along with its bounding region and content.

Two details in that structure cause most of the bugs in a first implementation, and neither is obvious from the field names.

The actual response shape from a live extraction. A table's cells are nested at content.body.cells, cell text sits at paragraph.content.text, and region.boundingBox is an eight-number polygon rather than an x, y, width, height rectangle.

A table element does not expose a top-level cells array. Its grid is nested at content.body.cells, where each cell carries rowIndex, columnIndex, and a paragraph object. Cell text then sits one level deeper still, at paragraph.content.text, because content is an object rather than a string. Reaching for cell["paragraph"]["content"] returns a dict, not the text you want.

Blank cells are the second detail. When a vendor leaves a cell empty, the API still returns the cell with its indices and a paragraph object, but that paragraph has no content key at all. An unguarded read raises KeyError partway through a document that looked fine in testing.

def element_text(element: dict) -> str:
    """Return an element's text, or an empty string when it carries none."""
    text = element.get("content", {}).get("text", "")
    return " ".join(text.split())


def cell_text(cell: dict) -> str:
    """Return a table cell's text, or an empty string when the cell is blank."""
    return element_text(cell.get("paragraph", {}))

In this code, element_text reads the nested content.text value and normalizes its whitespace, which matters because cell text can contain a literal \r\n where a label wraps across two lines. Using " ".join(text.split()) collapses those into single spaces, whereas .strip() leaves a mid-string newline untouched. cell_text then reuses that helper for table cells, returning an empty string for a blank cell instead of raising.

With the accessors in place, build a grid and read it row by row.

import re

FOOTER_LABELS = ("subtotal", "tax rate", "tax amount", "tax", "total due", "total")
HEADER_PATTERNS = {
    "vendor_name":    r"bill to:\s*(.+)",
    "invoice_number": r"invoice number:\s*(.+)",
    "invoice_date":   r"invoice date:\s*(.+)",
    "due_date":       r"due date:\s*(.+)",
    "payment_terms":  r"payment is due within (.+?) of",
}


def parse_invoice(structure_info: dict) -> dict:
    elements = structure_info["analyzeResult"]["elements"]
    invoice = {key: "" for key in HEADER_PATTERNS}
    invoice.update(line_items=[], subtotal="", tax="", total_due="")

    # Header fields come from paragraph elements above the table
    for element in elements:
        if element["type"] != "paragraph":
            continue
        text = element_text(element)
        for field, pattern in HEADER_PATTERNS.items():
            match = re.search(pattern, text, re.IGNORECASE)
            if match and not invoice[field]:
                invoice[field] = match.group(1).strip()

    tables = [element for element in elements if element["type"] == "table"]
    if not tables:
        return invoice

    grid: dict = {}
    for cell in tables[0]["content"]["body"]["cells"]:
        grid.setdefault(cell["rowIndex"], {})[cell["columnIndex"]] = cell_text(cell)

    # Resolve columns from the header row instead of assuming positions
    columns = {name.lower(): index for index, name in grid.get(0, {}).items() if name}

    def column_for(*candidates, default):
        for candidate in candidates:
            for name, index in columns.items():
                if candidate in name:
                    return index
        return default

    description_col = column_for("description", "item", default=1)
    quantity_col = column_for("qty", "quantity", default=2)
    unit_price_col = column_for("unit price", default=3)
    line_total_col = column_for("total", "amount", default=4)

    for row_index in sorted(index for index in grid if index > 0):
        row = grid[row_index]
        label = next(
            (value.lower().rstrip(":").strip() for value in row.values()
             if value.lower().rstrip(":").strip() in FOOTER_LABELS),
            None,
        )
        if label:
            value = row[max(row)]
            if label == "subtotal":
                invoice["subtotal"] = value
            elif label == "tax amount":
                invoice["tax"] = value
            elif label in ("total due", "total"):
                invoice["total_due"] = value
            continue
        if row.get(description_col):
            invoice["line_items"].append({
                "description": row.get(description_col, ""),
                "quantity": row.get(quantity_col, ""),
                "unit_price": row.get(unit_price_col, ""),
                "line_total": row.get(line_total_col, ""),
            })

    return invoice

In this code, you first walk the paragraph elements and pull header fields out with labelled regular expressions, which works because Foxit exposes each header line as its own element with its reading order preserved. You then flatten the table into a {rowIndex: {columnIndex: text}} grid and resolve column positions from the header row by name, so a vendor who adds a leading row-number column does not shift every field by one. Each subsequent row is classified before it is read, so that if any cell in the row matches a known footer label the row is treated as a total and its value taken from the last populated column, and otherwise the row becomes a line item. Scanning the whole row for the label is the part that matters, because footer labels do not sit in the first column.

Footer totals living inside the line-item table is convenient rather than awkward, since one pass over the cell grid covers line items and totals together. Form elements do not appear on a typical invoice, so there is no need to look for them.

Before and after

The two blocks below show the same data on either side of that mapping. First, one real cell exactly as the API returns it, taken verbatim from the run above:

{
  "paragraph": {
    "type": "paragraph",
    "content": {
      "text": "API Integration\r\nConsulting"
    },
    "region": {
      "page": 1,
      "boundingBox": [171, 300, 258, 300, 258, 328, 171, 328]
    },
    "id": "paragraph12",
    "paragraphOrder": 12
  },
  "rowSpan": 1,
  "columnSpan": 1,
  "rowIndex": 1,
  "columnIndex": 1,
  "region": {
    "page": 1,
    "boundingBox": [171, 300, 258, 300, 258, 328, 171, 328]
  },
  "score": 0.8555269837379456
}

That fragment is the shape of every cell you will handle. The text is nested at paragraph.content.text rather than sitting directly on the cell. The position arrives as an eight-number boundingBox polygon on both the cell and its paragraph, not as a rectangle. And the value itself contains a literal \r\n where the description wrapped onto a second line in the source table, which is the case .strip() silently fails to clean.

Second, the complete object parse_invoice returns for the whole document, which is what your backend actually consumes:

{
  "vendor_name": "Acme Corporation",
  "invoice_number": "INV-2025-0042",
  "invoice_date": "07/15/2025",
  "due_date": "08/14/2025",
  "payment_terms": "30 days",
  "line_items": [
    {
      "description": "API Integration Consulting",
      "quantity": "8",
      "unit_price": "$ 195.00",
      "line_total": "$1,560.00"
    },
    {
      "description": "Document Automation Setup",
      "quantity": "1",
      "unit_price": "$ 750.00",
      "line_total": "$ 750.00"
    }
  ],
  "subtotal": "$2,310.00",
  "tax": "$ 184.80",
  "total_due": "$2,494.80"
}

The wrapped description has become the single clean string "API Integration Consulting", the header fields have been lifted out of the paragraph elements above the table, and the four footer rows have been separated from the two genuine line items. That output is backend-ready, so you can write it straight to a database, push it to a reporting pipeline, or validate it against an accounts-payable schema without further parsing.

Common mistakes

• Dropping the path prefix. All four endpoints sit under /pdf-services/api/.... A bare /documents/{id}/download returns 404.
• Reading cells off the table element. The grid is nested at content.body.cells. A top-level cells lookup raises KeyError.
• Treating paragraph.content as a string. It is an object, so the text is at paragraph.content.text.
• Assuming footer labels are in column 0. On real invoices they commonly sit in the second-to-last column, with the value beside them.
• Forgetting blank cells. A blank cell keeps its paragraph object but carries no content key.
• Polling without a bound. A FAILED task never becomes COMPLETED, so an unbounded while True loop hangs.
• Trusting info.basicInfo.elementCounts. It can disagree with the length of the elements array, so size loops from the array itself.
• Using .strip() to clean cell text. A wrapped label contains a mid-string \r\n that .strip() leaves in place. Use " ".join(text.split()).

FAQ

What is invoice data extraction from PDF?

Invoice data extraction from PDF is the programmatic conversion of semi-structured PDF invoice content into a schema-typed data object. The source can be a digital-native PDF with an embedded text layer or a scanned image-only PDF that needs OCR first. The output is a structured record, typically JSON, with typed fields for header values, line items, and totals that downstream systems consume without manual parsing.

How do I extract line items from a PDF invoice?

Line items live in table elements inside StructureInfo.json. Read the grid from content.body.cells, where every cell carries a rowIndex and columnIndex, build a {rowIndex: {columnIndex: text}} dictionary, resolve the column positions from the header row, then read each data row in column order. Classify rows before reading them so footer totals are not appended as line items.

Can an extraction API handle scanned PDF invoices?

The PDF Structural Extraction API expects a PDF that already has a text layer. Tested against an image-only PDF, it returns no text and an empty table rather than an error. To handle scans, run the document through Foxit's OCR endpoint first (POST /pdf-services/api/documents/analyze/pdf-ocr with outputFormat set to PDF), then pass the OCR output through the four-step workflow. That makes five calls rather than four, and the OCR step is billed as its own credit.

What does the JSON output from PDF invoice extraction look like?

The downloaded ZIP unpacks to StructureInfo.json, holding an analyzeResult object with version, pages, info, and elements keys. The elements array carries every classified region, each with a type drawn from twelve values. A table element nests its grid at content.body.cells, and each cell's text sits at paragraph.content.text.

Why build a grid instead of iterating the cells array directly?

A grid keyed by row and column decouples your field mapping from the order the API happens to return cells in, and it lets you address a specific position directly, which is what the footer-label check needs. It also makes missing cells visible as absent keys rather than as silently shifted values.

What element types does the API classify?

The API classifies regions into twelve element types, including paragraph, table, title, image, form, and formula. On a typical invoice, paragraph elements carry the header fields while a single table element carries both line items and footer totals, so filtering by type lets you target only what your schema needs.

How should I handle invoices where footer totals sit outside the line-item table?

Some layouts place totals in a separate table element or in standalone paragraph elements below the main table. Keep the row-classification logic in its own function so you can apply it to a second table element, then fall back to scanning paragraph elements for currency-formatted strings next to known label text.

Wrapping up

The four-step workflow of upload, extract, poll, and download produces a typed, hierarchical JSON document from any digital-native invoice PDF. Post-processing the elements array through a row and column grid turns that into a clean invoice object your backend can consume directly. The same four calls extend to purchase orders, receipts, and any other tabular financial document, with only the mapping logic changing to match the target schema.

The Foxit PDF Structural Extraction API is part of the broader Foxit PDF Services API, which covers conversion, compression, OCR, and other document operations under the same credential set. The infrastructure is SOC 2 Type II certified, with GDPR-supporting features and HIPAA-aligned controls including BAA availability, which matters for teams processing financial documents under compliance review.

The complete script from this guide is available as extract_invoice.py if you want to run it before adapting it.

Create your free developer account and start turning invoice PDFs into structured JSON today. No credit card required, and the 500 credits on the free Developer plan are enough to build and test something real.