DEV Community: Maciej S.

Automating State DMV Title & Dealer Packets (TX 130-U, CA REG 227/343, FL HSMV 82040, MO Form 108) from Spreadsheets & JSON

Maciej S. — Thu, 22 Oct 2026 09:01:31 +0000

If you build software for independent auto dealerships, RV and trailer dealers, commercial fleet operators, or tag and title agencies, you eventually run into the state DMV PDF problem.

Your Dealer Management System (DMS) or spreadsheet holds clean, structured deal records: a 17-character vin, a 6-digit whole-mile odometer_reading, buyer_name, county, lienholder_elt_id, purchase_price, and trade_in_allowance. Yet every Friday, a title clerk spends hours re-typing those same rows into state-issued PDF forms—Texas Form 130-U and Form VTR-130-SOF, California REG 227 and REG 343, Florida HSMV 82040, Missouri Form 108 (DOR-108), New York DTF-802, or Ohio BMV 3774.

When engineering teams try to automate state DMV packets with a naive pypdf or pdf-lib script, they immediately hit four PDF architecture walls that do not exist in standard commercial forms:

Empty-password /Encrypt dictionaries and permission bitmasks that block modification or annotation (TX 130-U, OH BMV 3774).
Per-character split widget arrays where an 8-digit driver license number, 7-digit Dealer Report of Sale number, or 17-character VIN is shattered across individual 1-character /Tx nodes with inconsistent /Parent nesting and typos in official field names (CA REG 227).
Flattened vector forms with zero /AcroForm fields (OH BMV 3774) or hybrid PDFs where critical blocks—such as Notary jurats, Odometer combs, or VIN boxes—have no interactive widgets (CA REG 227 Notary section, NY DTF-802).
State-specific statutory math and formatting traps (tenths-of-a-mile rejection on FL HSMV 82040, county-based local tax routing on MO Form 108 and NY DTF-802, and mandatory two-sided completion on CA REG 343 and TX 130-U).

Below is an engineering breakdown of how official state DMV PDFs are constructed under the hood, followed by a production-grade Python + JSON pipeline (and MCP / spreadsheet workflow) that handles per-character field slicing, owner-encryption stripping, and coordinate-aware text overlay for flattened DMV forms.

1. Inside State DMV PDFs: Why Standard AcroForm Scripts Break

Unlike federal IRS forms—which follow a relatively uniform Adobe LiveCycle f1_1[0] naming convention—each state's Department of Motor Vehicles (or Department of Revenue / Public Safety) authors its PDFs with a completely different toolchain and security policy.

Pitfall A: Empty-Password Owner Encryption & Permission Bitmasks (`TX 130-U`, `OH BMV 3774`)

When you inspect the official Texas Department of Motor Vehicles Form 130-U (Form-130-U.pdf, Rev. 05/26, 2 pages, 106 fields: 55 text inputs, 48 checkboxes, 3 signature widgets) or Ohio Form BMV 3774, the PDF trailer contains an /Encrypt dictionary with an empty user password ("") and a restricted /P permissions bitmask that denies document assembly and annotation modification (modifyDenied: true, annotateDenied: true).

If your script opens Form-130-U.pdf without calling reader.decrypt("") and cloning the document tree into an unencrypted PdfWriter, downstream libraries either raise FileNotDecryptedError or write corrupted incremental updates that fail to open in Adobe Reader.

Pitfall B: Per-Digit Split Widgets and Inconsistent Hierarchy (`CA REG 227`)

In ISO 32000-1 §12.7.4.3, a multi-character comb field is supposed to be a single /FT /Tx widget with /MaxLen 17 and the /Ff Comb bit (1 << 24, or 16777216) set. When a PDF uses a true /Comb field, you write "1FTBW2CM5NKA00001" once to /V and the renderer spaces the characters across the 17 visual cells.

California DMV's Form REG 227 (Application for Duplicate or Paperless Title, 2 pages, 228 fields) does the exact opposite for ID numbers, Dealer Report of Sale (R/S) numbers, and Salesperson numbers. Instead of a single comb widget, the form author created separate 1-character AcroForm widgets for every digit—complete with typos in the official /T keys and inconsistent tree depths between Page 1 and Page 2:

# Actual AcroForm terminal field dump from official California DMV REG 227 (ca-reg-227.pdf):

# Header VIN & Plate fields use different suffixes on Page 1 vs. Page 2:
'License Plate/CF Number1'    -> /Tx | TU: "enter vehicle License Plate or vessel C F Number."
'Vehicle/Vessel ID/Number1'   -> /Tx | TU: "enter Vehicle or hull identification number"
'License Plate/CF Number122'  -> /Tx | TU: "This side for new owners. Each new owner must sign below..."
'Vehicle/Vessel ID/Number211' -> /Tx | TU: "enter Vehicle or hull identification number"

# Section 1 Owner 1 CA DL/ID (8 separate 1-char widgets at depth 2):
'1 DL/ID Number-1.0' -> /Tx | TU: "driver's license or i d card number. enter first digit."
'1 DL/ID Number-1.1' -> /Tx | TU: "enter second digit."
...
'1 DL/ID Number-1.7' -> /Tx | TU: "enter eighth digit."

# Section 1 Co-Owner CA DL/ID (digit 8 suddenly drops to depth 3!):
'1 DL/ID Number-2.0'   -> /Tx | TU: "driver license number or i d number for co-owner. enter first digit."
...
'1 DL/ID Number-2.6'   -> /Tx | TU: "enter seventh digit"
'1 DL/ID Number-2.7.0' -> /Tx | TU: "enter eighth digit"

# Section 6 New Owner CA DL/ID (official PDF spells "Number" as "Numer" and "CArd"):
'6 DL/ID Card Numer-1.0.1.0' -> /Tx | TU: "driver license or i d card number. enter first digit"
'6 DL/ID Card Numer-1.1'     -> /Tx | TU: "enter second digit"
...
'6 DL/ID Card Numer-1.7.0'   -> /Tx | TU: "enter eighth digit"
'6 DL/ID CArd Number-2.0'    -> /Tx | TU: "driver license or i d card number. enter first digit"

# Section 7 ELT Number (9-digit Electronic Lien & Title ID split into three 3-digit boxes):
'7 ELT #.0'   -> /Tx | TU: "enter first three digits of electronic lienholder i d number"
'7 ELT #.1.0' -> /Tx | TU: "next three digits."
'7 ELT #.1.1' -> /Tx | TU: "last three digits."

# Section 8 Dealer Release R/S Number & Salesperson Number (7 separate 1-char boxes each):
'10 R/S Number-1.0' .. '10 R/S Number-1.6'
'10 Salesperson Number-1.0' .. '10 Salesperson Number-1.6'

If your DMS exports buyer_dl_number: "D4129876" and elt_number: "C91044821", a flat key-value mapper cannot populate CA REG 227. Your mapper must support string-slicing rules (slice: [start, end]) that distribute a single spreadsheet column across an ordered list of target widget names.

Pitfall C: Zero-Field Flattened Vector PDFs (`OH BMV 3774`, `NY DTF-802` Sections)

When you run a field inspection script against Ohio's official Form BMV 3774 (Application for Certificate of Title to a Motor Vehicle, bmv3774.pdf), here is what the /Root catalog contains:

Pages: 1 | Encrypted: True | Total /AcroForm fields: 0
/Root keys: ['/Lang', '/MarkInfo', '/Metadata', '/OpenAction', '/PageLayout', '/Pages', '/StructTreeRoot', '/Type', '/ViewerPreferences']

There is no /AcroForm dictionary in the document catalog at all. Every input box, VIN grid, and checkbox on OH BMV 3774 is drawn purely with PDF content-stream path operators (m, l, re, S). Similarly, New York's Form DTF-802 (Statement of Transaction — Sale or Gift of Motor Vehicle) and the Notary block on California's REG 227 contain visual boxes with no underlying /Widget annotations. To batch-fill those forms from a CSV deal log, you must either reconstruct /AcroForm widgets over the vector boxes or merge a coordinate-mapped ReportLab/PyMuPDF text overlay onto the page stream.

2. State-by-State DMV Dealer & Fleet Packet Comparison

Before writing the batch-fill engine, here is a quick reference across the eight highest-volume state DMV title, sale, and driver onboarding forms:

State Form	Primary Dealer / Fleet Use Case	PDF Architecture & Field Quirk	Critical Filing & Data Validation Rule
Texas Form 130-U	Application for Texas Title and/or Registration	2 pages, 106 AcroForm fields (`55 /Tx`, `48 /Btn`, `3 /Sig`), owner-encrypted (`modifyDenied: true`), 96.2% named fields.	Must be filed within 30 days of sale at County Tax Assessor-Collector. Applicant signature must be original; non-licensed private seller does not need to sign 130-U.
Texas Form VTR-130-SOF	Bonded Title Application or Tax Collector Hearing Statement of Fact	Paired with `130-U` when clearing missing-title trade-ins, auction units, or utility trailers.	Submitted first to a TxDMV Regional Service Center to obtain a Notice of Determination (`VTR-130-ND`) before filing `130-U`. VIN and price must match `130-U`.
California REG 227	Application for Duplicate or Paperless Title	2 pages, 228 AcroForm fields; per-digit split widgets for DL/ID (`8 boxes`), R/S (`7 boxes`), Salesperson (`7 boxes`), and 3-part ELT (`3x3`); flattened Notary block.	Sections 1–3 replace a lost title; Sections 4–7 transfer ownership when title is missing. Section 5 (Lienholder Release) must be notarized. Write `"NONE"` if no lienholder.
California REG 343	Application for Title or Registration (Out-of-State / Original)	2-page application requiring both sides (Sections 1–3 on Page 1; Cost, CA Entry Date, and Signatures in Sections 4–8 on Page 2).	Section 5 requires the exact date the vehicle entered California. Whole miles only on odometer. Always write `"NONE"` in Section 3 if there is no lienholder.
Florida HSMV 82040	Application for Certificate of Motor Vehicle Title	2-page FLHSMV title application (often paired with `HSMV 82050` Notice of Sale). Multi-owner `AND` / `OR` conjunction checkboxes in Section 1.	Section 6 Odometer Declaration accepts whole miles only (no tenths). Out-of-state transfers require Section 8 physical VIN verification on Page 2.
Missouri Form 108 (DOR-108)	Application for Missouri Title and License	Dense 1-page multi-column layout (instructions on Page 2) combining Owner, TOD Beneficiary, Vehicle, Lien, and Trade-In/Rebate net tax calculation table.	Missouri local vehicle sales tax is based on the buyer's residential County and city, not the dealership location. Late penalty is $25 per 30 days after day 30 (up to $200).
New York Form DTF-802	Statement of Transaction — Sale or Gift of Motor Vehicle, Trailer, ATV, or Vessel	Joint NYS Tax & Finance / DMV form (`DTF-802 (5/15)`) with tight 17-char VIN boxes and non-interactive sections; filed alongside `MV-82`.	Section 6 (Seller/Donor Affidavit) must be signed by the seller if claiming a family gift exemption or below-fair-market-value sale.
Ohio Form BMV 3774	Application for Certificate of Title to a Motor Vehicle	1-page owner-encrypted PDF with 0 AcroForm fields (100% flattened vector paths).	Filed at Ohio County Clerk of Courts Title Office. Applicant must sign in the presence of a Notary Public or Deputy Clerk (never pre-sign before notarization).
Texas Form DL-14A	Texas Adult Driver License or ID Card Application	2-page Texas DPS onboarding packet used by fleet and relocation coordinators for out-of-state commercial and corporate drivers.	Physical residence address cannot be a P.O. Box. Applicant must wait to sign Page 2 until instructed by the Texas DPS clerk at the counter.

If you want to inspect the field layouts or fill individual packets directly in the browser before automating a batch, you can open the interactive templates for Texas Form 130-U Title & Registration, California DMV Form REG 227 Duplicate Title, California Form REG 343 Original Title/Registration, Florida Form HSMV 82040 Motor Vehicle Title, Missouri DOR Form 108 Title & License, New York Form DTF-802 Statement of Transaction, or Texas DPS Form DL-14A Driver License Application.

3. Inspecting Any State DMV PDF (`inspect_dmv_pdf.py`)

Before building a mapping file for a state DMV form, run this diagnostic script. It automatically decrypts empty owner passwords, reports whether the PDF contains interactive /AcroForm widgets or is a flattened vector form (like OH BMV 3774), and dumps every terminal widget's /T key, /FT type, /MaxLen, /Comb flag, and /TU tooltip:

#!/usr/bin/env python3
"""
inspect_dmv_pdf.py
Diagnose state DMV PDFs: detect owner-password locks, flattened 0-field pages,
comb flags, and split per-character AcroForm widgets.
Requires: pip install pypdf
"""

import json
import sys
from pypdf import PdfReader

COMB_FLAG = 1 << 24  # ISO 32000-1 bit 25 (16777216)


def walk_widgets(node_ref, prefix="", out=None):
    if out is None:
        out = []
    node = node_ref.get_object()
    t_val = str(node.get("/T", ""))
    full_name = f"{prefix}.{t_val}" if prefix and t_val else (t_val or prefix)

    kids = node.get("/Kids")
    if kids:
        for kid_ref in kids:
            walk_widgets(kid_ref, full_name, out)
        return out

    ft = str(node.get("/FT", ""))
    if not ft and "/Parent" in node:
        ft = str(node["/Parent"].get_object().get("/FT", ""))

    ff = int(node.get("/Ff", 0) or 0)
    max_len = node.get("/MaxLen")
    rect = [round(float(x), 2) for x in node.get("/Rect", [])]

    out.append({
        "full_name": full_name,
        "terminal_name": t_val,
        "type": ft,
        "max_len": int(max_len) if max_len is not None else None,
        "is_comb": bool(ff & COMB_FLAG),
        "tooltip": str(node.get("/TU", "")),
        "rect": rect,
    })
    return out


def inspect_pdf(pdf_path: str) -> None:
    reader = PdfReader(pdf_path)
    was_encrypted = reader.is_encrypted
    if was_encrypted:
        reader.decrypt("")

    root = reader.trailer["/Root"].get_object()
    acroform = root.get("/AcroForm")
    widgets = []
    if acroform:
        for ref in acroform.get_object().get("/Fields", []):
            walk_widgets(ref, "", widgets)

    summary = {
        "file": pdf_path,
        "pages": len(reader.pages),
        "owner_encrypted": was_encrypted,
        "has_acroform": bool(acroform),
        "total_terminal_widgets": len(widgets),
        "verdict": (
            "flattened_vector_or_scan"
            if len(widgets) == 0
            else "interactive_acroform"
        ),
        "sample_widgets": widgets[:15],
    }
    print(json.dumps(summary, indent=2))


if __name__ == "__main__":
    inspect_pdf(sys.argv[1])

4. Unified Deal Log CSV & Mapping Schema (Direct, Sliced, and Coordinate Overlay)

To handle all three DMV PDF patterns—standard AcroForm fields (TX 130-U, FL HSMV 82040, MO Form 108), split per-character widgets (CA REG 227), and flattened vector forms (OH BMV 3774)—from the same DMS spreadsheet, we structure our mapping JSON with three target primitives:

Direct field string: "vin": "Vehicle/Vessel ID/Number1" (writes the normalized value directly to /V).
Per-character / substring slice array: distributes characters value[start:end] across an array of split widgets (such as CA REG 227's 8-box Driver License number or 3-box ELT number).
Coordinate overlay fallback (overlays): draws crisp text at exact (page, x, y) coordinates when a form (or a specific section like a Notary or VIN box) lacks /AcroForm widgets.

Here is a sample DMS export (dealer_title_batch.csv) with synthetic vehicle deals:

deal_id,state,vin,year,make,model,body_type,plate_no,odometer_miles,sale_date,purchase_price,trade_in_allowance,buyer_name,buyer_dl,buyer_address,buyer_city,buyer_state,buyer_zip,buyer_county,seller_dealer_name,dealer_number,rs_number,salesperson_number,lienholder_name,lienholder_elt,lienholder_address,lienholder_city,lienholder_state,lienholder_zip
DEAL_101,CA,5TDGZRAH4NS000101,2022,TOYOTA,HIGHLANDER,SUV,8Xample1,29850,10/18/2026,33900.00,0.00,"SAMPLE, DEVON P",F8194021,220 Sample Coast Hwy,Irvine,CA,92618,Orange,PACIFIC COAST AUTO LLC,D90412,1234567,S765432,PACIFIC SAMPLE CREDIT UNION,C91044821,PO Box 4000,Anaheim,CA,92803
DEAL_102,TX,1FTBW2CM5NKA00202,2022,FORD,TRANSIT,VN,TX99012,41200,10/19/2026,38500.00,8500.00,"SAMPLE LOGISTICS LLC",40192831,400 Sample Industrial Pkwy,Austin,TX,78744,Travis,LONE STAR FLEET SALES,P110293,0000000,0000000,NONE,,NONE,,,
DEAL_103,FL,1GNSKCKD8PR000303,2023,CHEV,TAHOE,UT,FL44019,19640,10/20/2026,54200.00,12000.00,"SAMPLE, VALERIA G",S5148821,1200 Sample Brickell Ave,Miami,FL,33131,Miami-Dade,BISCAYNE MOTORS INC,VI1029384,0000000,0000000,SUNSHINE SAMPLE CREDIT UNION,201948291,PO Box 9000,Miami,FL,33101

And here is the mapping configuration (ca_reg_227_mapping.json) that maps a single CSV row into CA REG 227's duplicate header fields, 8-box Driver License array, 3-box ELT code, and 7-box Dealer Report of Sale (R/S) number:

{
  "output_pattern": "CA_REG227_{deal_id}_{vin}.pdf",
  "defaults": {
    "lienholder_name": "NONE"
  },
  "direct_fields": {
    "plate_no": ["License Plate/CF Number1", "License Plate/CF Number122"],
    "vin": ["Vehicle/Vessel ID/Number1", "Vehicle/Vessel ID/Number211"],
    "year_make": ["Year/Make", "Year/Make2"],
    "buyer_name": ["true full name of new owner, last, first, middle, suffix, business name, or lessor"],
    "buyer_address": ["physical residence or business address.0"],
    "buyer_city": ["6 City-1"],
    "buyer_state": ["6 States1"],
    "buyer_zip": ["6 Zip Code-1"],
    "buyer_county": ["county residence or county where vehicle or vessle is princi.0"],
    "purchase_price": ["Purchase price"],
    "sale_date": ["Date Purchased", "10 Date Sold-1"],
    "lienholder_name": ["7 Name New Legal Owner"],
    "lienholder_address": ["Physical residence or business address.0"],
    "lienholder_city": ["7 City.0"],
    "lienholder_state": ["7 State.0"],
    "lienholder_zip": ["7 Zip Code.0"],
    "seller_dealer_name": ["10 Name of Dealership-1"],
    "dealer_number": ["10 Dealer Number-1"]
  },
  "sliced_fields": {
    "buyer_dl": [
      {"field": "6 DL/ID Card Numer-1.0.1.0", "slice": [0, 1]},
      {"field": "6 DL/ID Card Numer-1.1", "slice": [1, 2]},
      {"field": "6 DL/ID Card Numer-1.2", "slice": [2, 3]},
      {"field": "6 DL/ID Card Numer-1.3", "slice": [3, 4]},
      {"field": "6 DL/ID Card Numer-1.4", "slice": [4, 5]},
      {"field": "6 DL/ID Card Numer-1.5", "slice": [5, 6]},
      {"field": "6 DL/ID Card Numer-1.6", "slice": [6, 7]},
      {"field": "6 DL/ID Card Numer-1.7.0", "slice": [7, 8]}
    ],
    "lienholder_elt": [
      {"field": "7 ELT #.0", "slice": [0, 3]},
      {"field": "7 ELT #.1.0", "slice": [3, 6]},
      {"field": "7 ELT #.1.1", "slice": [6, 9]}
    ],
    "rs_number": [
      {"field": "10 R/S Number-1.0", "slice": [0, 1]},
      {"field": "10 R/S Number-1.1", "slice": [1, 2]},
      {"field": "10 R/S Number-1.2", "slice": [2, 3]},
      {"field": "10 R/S Number-1.3", "slice": [3, 4]},
      {"field": "10 R/S Number-1.4", "slice": [4, 5]},
      {"field": "10 R/S Number-1.5", "slice": [5, 6]},
      {"field": "10 R/S Number-1.6", "slice": [6, 7]}
    ]
  }
}

5. Production Python Batch Filler for State DMV Packets (`batch_fill_dmv_packets.py`)

The script below validates VINs (17 characters, excluding I, O, and Q per 49 CFR § 565) and whole-mile odometer readings, strips empty-password owner encryption (TX 130-U, OH BMV 3774), populates both standard /AcroForm fields and per-digit sliced widgets (CA REG 227), and optionally merges coordinate-mapped text overlays for flattened vector sections:

#!/usr/bin/env python3
"""
batch_fill_dmv_packets.py
Batch-generate state DMV title & registration packets (TX 130-U, CA REG 227/343,
FL HSMV 82040, MO Form 108, NY DTF-802, OH BMV 3774) from DMS CSV/Excel exports.
Requires: pip install pypdf reportlab
"""

import csv
import io
import json
import re
import sys
from pathlib import Path
from pypdf import PdfReader, PdfWriter
from pypdf.generic import BooleanObject, NameObject, TextStringObject

VIN_CLEAN_RE = re.compile(r"[^A-HJ-NPR-Z0-9]")


def normalize_vin(raw_vin: str) -> str:
    """Normalize a 17-character VIN (uppercase, strip spaces, flag invalid I/O/Q)."""
    cleaned = VIN_CLEAN_RE.sub("", str(raw_vin or "").upper().strip())
    if len(cleaned) != 17:
        raise ValueError(f"Invalid VIN '{raw_vin}' (expected 17 valid characters, got {len(cleaned)})")
    return cleaned


def normalize_whole_miles(raw_miles: str) -> str:
    """Strip commas and tenths of a mile (required by FL HSMV 82040, CA REG 343, TX 130-U)."""
    text = str(raw_miles or "").strip().replace(",", "")
    if "." in text:
        text = text.split(".", 1)[0]
    if not text.isdigit():
        raise ValueError(f"Invalid odometer reading '{raw_miles}'")
    return text


def index_widgets(acroform_obj) -> dict:
    """Index terminal widgets by both terminal /T name and full dotted path."""
    by_name = {}

    def walk(ref, prefix=""):
        node = ref.get_object()
        t_val = str(node.get("/T", ""))
        full = f"{prefix}.{t_val}" if prefix and t_val else (t_val or prefix)
        kids = node.get("/Kids")
        if kids:
            for kid_ref in kids:
                walk(kid_ref, full)
            return
        if t_val:
            by_name[t_val] = node
        if full:
            by_name[full] = node

    for root_ref in acroform_obj.get("/Fields", []):
        walk(root_ref)
    return by_name


def set_widget(widget, value: str) -> None:
    ft = str(widget.get("/FT", ""))
    if not ft and "/Parent" in widget:
        ft = str(widget["/Parent"].get_object().get("/FT", ""))

    if ft == "/Btn":
        truthy = str(value).strip().lower() in {"1", "true", "yes", "x", "on", "checked"}
        checked_state = NameObject("/Yes")
        ap = widget.get("/AP")
        if ap and "/N" in ap.get_object():
            normal = ap.get_object()["/N"].get_object()
            for key in getattr(normal, "keys", lambda: [])():
                if str(key) != "/Off":
                    checked_state = NameObject(str(key))
                    break
        state = checked_state if truthy else NameObject("/Off")
        widget[NameObject("/V")] = state
        widget[NameObject("/AS")] = state
    else:
        widget[NameObject("/V")] = TextStringObject(str(value or ""))
        if NameObject("/AP") in widget:
            del widget[NameObject("/AP")]


def apply_coordinate_overlays(writer: PdfWriter, overlays: list, row: dict) -> None:
    """Fallback overlay for flattened 0-field DMV PDFs (e.g., OH BMV 3774 or NY DTF-802 sections)."""
    if not overlays:
        return
    from reportlab.pdfgen import canvas

    by_page = {}
    for item in overlays:
        by_page.setdefault(int(item["page"]), []).append(item)

    for page_idx, items in by_page.items():
        page = writer.pages[page_idx]
        box = page.mediabox
        packet = io.BytesIO()
        c = canvas.Canvas(packet, pagesize=(float(box.width), float(box.height)))
        for item in items:
            text = str(row.get(item["column"], "")).strip()
            if not text:
                continue
            c.setFont(item.get("font", "Helvetica"), float(item.get("size", 9)))
            char_spacing = float(item.get("char_spacing", 0))
            if char_spacing > 0:
                # Render comb-spaced characters over flattened VIN / Odometer boxes
                x_cursor = float(item["x"])
                for ch in text:
                    c.drawString(x_cursor, float(item["y"]), ch)
                    x_cursor += char_spacing
            else:
                c.drawString(float(item["x"]), float(item["y"]), text)
        c.save()
        packet.seek(0)
        overlay_reader = PdfReader(packet)
        page.merge_page(overlay_reader.pages[0])


def fill_dmv_row(template_pdf: str, mapping: dict, raw_row: dict, out_dir: Path) -> Path:
    row = dict(raw_row)
    row["vin"] = normalize_vin(row["vin"])
    row["odometer_miles"] = normalize_whole_miles(row["odometer_miles"])
    row["year_make"] = f"{row.get('year', '')} {row.get('make', '')}".strip()

    for col, default_val in mapping.get("defaults", {}).items():
        if not str(row.get(col, "")).strip():
            row[col] = default_val

    reader = PdfReader(template_pdf)
    if reader.is_encrypted:
        reader.decrypt("")

    writer = PdfWriter()
    writer.append(reader)

    root = writer._root_object
    if NameObject("/AcroForm") in root:
        acroform = root[NameObject("/AcroForm")].get_object()
        if NameObject("/XFA") in acroform:
            del acroform[NameObject("/XFA")]
        acroform[NameObject("/NeedAppearances")] = BooleanObject(True)
        widgets = index_widgets(acroform)

        # 1. Populate standard direct AcroForm fields (including multi-page duplicates)
        for col, targets in mapping.get("direct_fields", {}).items():
            val = str(row.get(col, ""))
            for target_name in (targets if isinstance(targets, list) else [targets]):
                if target_name in widgets:
                    set_widget(widgets[target_name], val)

        # 2. Populate per-digit / substring sliced widgets (e.g., CA REG 227 DL/ID, ELT, R/S)
        for col, rules in mapping.get("sliced_fields", {}).items():
            val = str(row.get(col, "")).strip()
            for rule in rules:
                start, end = rule["slice"]
                piece = val[start:end] if len(val) > start else ""
                target_name = rule["field"]
                if target_name in widgets:
                    set_widget(widgets[target_name], piece)

    # 3. Apply coordinate overlays for flattened vector forms / sections
    apply_coordinate_overlays(writer, mapping.get("overlays", []), row)

    out_path = out_dir / mapping["output_pattern"].format(**row)
    with open(out_path, "wb") as f:
        writer.write(f)
    return out_path


def main(template_pdf: str, mapping_json: str, csv_path: str, out_dir_str: str) -> None:
    mapping = json.loads(Path(mapping_json).read_text(encoding="utf-8"))
    out_dir = Path(out_dir_str)
    out_dir.mkdir(parents=True, exist_ok=True)

    with open(csv_path, newline="", encoding="utf-8-sig") as f:
        for idx, row in enumerate(csv.DictReader(f), start=1):
            out_path = fill_dmv_row(template_pdf, mapping, row, out_dir)
            print(f"[{idx}] Generated {out_path}")


if __name__ == "__main__":
    if len(sys.argv) != 5:
        print("Usage: python batch_fill_dmv_packets.py template.pdf mapping.json deals.csv ./out")
        sys.exit(1)
    main(sys.argv[1], sys.argv[2], sys.argv[3], sys.argv[4])

We verified inspect_dmv_pdf.py and batch_fill_dmv_packets.py directly against the official ca-reg-227.pdf (228 AcroForm widgets) and oh-bmv-3774.pdf (owner-encrypted, 0 AcroForm fields):

On ca-reg-227.pdf, the sliced mapper populates all 8 individual digits of '6 DL/ID Card Numer-1.0.1.0'..'6 DL/ID Card Numer-1.7.0', splits the 9-character ELT ID across '7 ELT #.0', '7 ELT #.1.0', and '7 ELT #.1.1', and mirrors the 17-character VIN across both Page 1 ('Vehicle/Vessel ID/Number1') and Page 2 ('Vehicle/Vessel ID/Number211').
On oh-bmv-3774.pdf, reader.decrypt("") strips the owner-password restriction so the coordinate overlay merges cleanly into an unlocked, printable PDF ready for the County Clerk of Courts Title Office notary jurat.

6. Automating DMV Dealer Batches from Excel/CSV or MCP Without Custom Coordinate Maps

Maintaining JSON slice arrays for 6 DL/ID Card Numer-1.0.1.0 or measuring (x, y) coordinates for flattened state forms works well when you have a dedicated engineering team maintaining a single state's packet. When a dealership group, RV/trailer dealer, fleet manager, or tag agency operates across multiple states—or just wants to turn a Friday DMS spreadsheet export into 50 ready-to-sign title packets:

Self-Serve Excel / CSV Batch Mail Merge: In our fill PDF forms from Excel or CSV workflow, adjacent per-character boxes (such as 17-character VIN combs and split DL/ID grids) are unified into a single logical field, while flattened 0-field PDFs are automatically detected so you can map one DMS column (vin, odometer_miles, buyer_name, lienholder_name) once, preview a 5-row sample free, edit any cell inline in the browser grid, and export a ZIP of completed PDFs.
Multi-Form Dealership Packets from One Spreadsheet: A Texas dealer can run the exact same DMS CSV against Texas Form 130-U and Bonded Title Statement of Fact (VTR-130-SOF); a California dealer can pair CA DMV Form REG 227 and Form REG 343; and multi-state operations can generate Florida HSMV 82040, Missouri Form 108, New York Form DTF-802, and Texas DPS Form DL-14A packets without writing per-state PDF parser code.
MCP / Agent Integration: If you are building an internal dealership back-office agent or n8n pipeline, the @justfill/mcp server exposes deterministic schema inspection (inspect_pdf) and strict field population (fill_pdf) over the Model Context Protocol so your DMS webhook can generate reviewable title packets on demand.

7. Pre-Flight Checklist for Multi-State DMV Title Batches

Before running a batch of 25 to 500 vehicle rows for the county tax office or tag agency:

Validate 17-Character VINs Against I, O, and Q: OCR scans of wholesale auction sheets frequently misread 0 as O or 1 as I. Reject or flag any VIN containing I, O, or Q before generating the PDF.
Enforce Whole-Mile Odometer Formatting: Strip .0 decimals or tenths of a mile from DMS exports—FL HSMV 82040 (Section 6), CA REG 343 (Section 1), and TX 130-U (Box 9) require whole miles only.
Populate Explicit "NONE" for Cash Deals: On CA REG 227 (Sections 2 & 7), CA REG 343 (Section 3), and TX 130-U (Box 34), leaving the Lienholder / Legal Owner field blank instead of writing "NONE" is one of the most common reasons DMV clerks flag a packet for review.
Respect Wet-Ink & Notary Signature Rules: Keep signature widgets blank when the state requires an in-person witnessed signature—such as the sworn Notary / Deputy Clerk jurat on OH BMV 3774, the Section 5 Lienholder release notary block on CA REG 227, the counter signature on TX DL-14A, or the original applicant signature on TX 130-U.

Disclosure: I am the solo developer of JustFill.

AI disclosure: AI coding agents drafted and revised this article and verified the code examples above.

How to Batch-Fill USCIS Immigration Packets (G-28, I-129, I-140, I-485, I-765) from CSV/JSON Without Adobe Acrobat or XFA Desync

Maciej S. — Thu, 22 Oct 2026 08:54:14 +0000

If you work in immigration legal ops, corporate mobility HR, or build document automation for law firms, you already know the arithmetic of an employment-based or family-based USCIS filing:

A single H-1B / L-1 / O-1 nonimmigrant packet (Form G-28 + Form I-129) spans 42 pages and 1,081 interactive PDF fields (101 fields in G-28 + 980 fields in I-129).
A single concurrent EB-2 / EB-3 green card filing (Form G-28 + Form I-140 + Form I-485 + Form I-765) spans 43 pages and 1,283 fields (101 + 261 + 760 + 161).
Across a 40-employee H-1B cap season batch or a 25-family adjustment cohort, paralegals end up re-typing the same petitioner FEIN, attorney bar number, beneficiary passport number, I-94 record, and physical address tens of thousands of times.

Yet when engineering teams try to automate G-28, I-129, I-140, I-485, I-765, or N-400 from a clean CSV, Excel (.xlsx), or JSON payload using standard Python or Node.js PDF libraries, they immediately hit three structural walls baked into official uscis.gov PDFs:

Owner Encryption + /Perms Usage-Rights Locks: 24 of 26 USCIS PDFs carry empty-password owner encryption (modifyDenied: true) plus an Adobe /UR3 digital signature inside /Root/Perms.
Cryptic LiveCycle Subform Paths: Instead of semantic names like beneficiary_last_name, fields are nested inside XFA-mirrored trees like form1[0].#subform[0].Pt1Line1a_FamilyName[0]—and inconsistent across forms (Pt1Line1a_FamilyName[0] on one form vs. Part2_Line1_FamilyName[0] on the next).
Hybrid /XFA vs. /AcroForm Desynchronization: Updating /AcroForm /Fields /V without stripping /AcroForm/XFA causes Windows Adobe Acrobat to prioritize the empty <xfa:datasets> XML stream and display every populated field 100% blank.

Below is a complete engineering breakdown of how official USCIS packet PDFs are structured, how to extract a unified cross-form schema using /TU (tooltip) metadata, and how to batch-fill multi-form USCIS packets from CSV/JSON in Python or the browser.

1. Structural Anatomy of a 6-Form USCIS Filing Packet

When we audited all 26 USCIS forms in our structural study using pypdf 6.6 and pikepdf, every core petition and application shared the same Adobe LiveCycle / AEM Forms hybrid architecture:

Form Code	Official Purpose	Pages	Size	Total Fields	Field Breakdown (`Tx` / `Btn` / `Ch`)	Hybrid `/XFA`	Owner `/Encrypt` + `modifyDenied`
Form G-28	Notice of Entry of Appearance as Attorney	4	387 KB	101	`76 Tx`, `23 Btn`, `2 Ch`	Yes	Yes
Form I-129	Petition for a Nonimmigrant Worker (H-1B, L-1, O-1)	38	2,242 KB	980	`623 Tx`, `333 Btn`, `24 Ch`	Yes	Yes
Form I-140	Immigrant Petition for Alien Workers (EB-1/2/3)	8	513 KB	261	`179 Tx`, `79 Btn`, `3 Ch`	Yes	Yes
Form I-485	Application to Register Permanent Residence	24	1,175 KB	760	`334 Tx`, `416 Btn`, `10 Ch`	Yes	Yes
Form I-765	Application for Employment Authorization (EAD)	7	456 KB	161	`119 Tx`, `38 Btn`, `4 Ch`	Yes	Yes
Form N-400	Application for Naturalization	14	758 KB	440	`237 Tx`, `198 Btn`, `5 Ch`	Yes	Yes

Notice two things right away:

Zero native /Btn radio groups (radios: 0): Even mutually exclusive "Yes / No" questions on I-485 (416 checkboxes) and I-129 (333 checkboxes) are implemented as individual checkbox widgets where each /AP /N dictionary defines a specific export key (typically /Y, /N, /1, or /Yes, paired with /Off).
Every single form is both xfa: true and encrypted: true: Before your script can modify widgets or merge pages into a single filing packet, you must decrypt the empty-password owner lock and remove both /AcroForm/XFA and /Root/Perms.

2. Why One Canonical JSON Record Can't Naive-Match Across USCIS Forms

Suppose you have a canonical JSON or CSV row representing one beneficiary and one sponsoring employer/attorney:

{
  "case_id": "2026-H1B-042",
  "attorney.family_name": "Vance",
  "attorney.given_name": "Elena",
  "attorney.bar_number": "CA-294810",
  "attorney.firm_name": "Vance Global Immigration LLP",
  "employer.legal_name": "Acme Robotics Inc.",
  "employer.fein": "94-1234567",
  "beneficiary.family_name": "Kowalski",
  "beneficiary.given_name": "Jan",
  "beneficiary.alien_number": "A-219847561",
  "beneficiary.dob": "04/19/1991",
  "beneficiary.i94_number": "84920194821"
}

If you inspect the /AcroForm /Fields trees across g-28.pdf, i-129.pdf, i-140.pdf, i-485.pdf, and i-765.pdf, the beneficiary's last name lives at a different hierarchical path on every form:

Form G-28  -> form1[0].#subform[1].Pt3Line5a_FamilyName[0]
Form I-129 -> form1[0].#subform[2].Part3_Line1a_FamilyName[0]
Form I-140 -> form1[0].#subform[1].Pt3Line1a_FamilyName[0]
Form I-485 -> form1[0].#subform[0].Pt1Line1a_FamilyName[0]
Form I-765 -> form1[0].#subform[0].Pt1Line1a_FamilyName[0]
Form N-400 -> form1[0].#subform[0].Pt2Line1_FamilyName[0]

Fortunately, USCIS embeds detailed human-readable descriptions inside every widget's /TU (Alternate Field Name / Tooltip) entry for Section 508 accessibility—for example:

312 0 obj
<<
  /Type /Annot
  /Subtype /Widget
  /FT /Tx
  /T (Pt1Line1a_FamilyName[0])
  /TU (Part 1. Information About You. Line 1a. Family Name (Last Name))
  /MaxLen 35
  /DA (/CourierStd 10 Tf 0 g)
  /Rect [ 54.00 582.10 294.00 596.50 ]
>>
endobj

By extracting (full_field_path, /FT, /TU, /MaxLen, /AP/N states) once per form edition, you can build a deterministic Canonical Packet Mapping (packet_map.json) that binds one canonical key (beneficiary.family_name, attorney.bar_number, employer.fein) to its exact target widget across G-28, I-129, I-140, I-485, I-765, and N-400.

3. Python Pipeline: Inspecting & Batch-Filling a Multi-Form USCIS Packet

Below is a complete, self-contained Python pipeline (pikepdf + pypdf) that:

Unlocks official USCIS PDFs (G-28, I-140, I-485, I-765, I-129, N-400) by stripping owner encryption, /Root/Perms, and /AcroForm/XFA.
Maps a single canonical CSV/JSON record across every form in the packet.
Correctly sets both /V and /AS on USCIS checkboxes (NameObject("/Y"), NameObject("/1"), etc.) while clearing cached /AP appearance streams on modified text fields so every viewer renders the text cleanly.

#!/usr/bin/env python3
"""
uscis_packet_batch_filler.py
Batch-generate multi-form USCIS immigration packets (G-28, I-129, I-140, I-485, I-765, N-400)
from CSV or JSON while stripping hybrid /XFA streams and /Perms UR3 locks.
"""

import csv
import json
import sys
from pathlib import Path
import pikepdf
from pypdf import PdfReader, PdfWriter
from pypdf.generic import BooleanObject, NameObject, TextStringObject


def index_terminal_widgets(node_ref, prefix="", out=None):
    if out is None:
        out = {}
    node = node_ref.get_object()
    name = str(node.get("/T", ""))
    full_name = f"{prefix}.{name}" if prefix and name else (name or prefix)

    if "/Kids" in node:
        for kid_ref in node["/Kids"]:
            index_terminal_widgets(kid_ref, full_name, out)
    else:
        out[full_name] = node
        if name:
            # Also index by terminal key for convenience when unique
            out.setdefault(name, node)
    return out


def set_uscis_widget_value(widget, raw_value: str) -> None:
    ft = widget.get("/FT")
    if ft == "/Btn":
        ap_n = widget.get("/AP", {}).get("/N", {})
        on_states = [k for k in ap_n.keys() if k != "/Off"]
        truthy = str(raw_value).strip().lower() in ("true", "yes", "y", "1", "x", "checked")

        target_state = NameObject("/Off")
        if truthy and on_states:
            # If caller passed an explicit state like "/Y" or "/1", honor it; else pick first on-state
            explicit = f"/{str(raw_value).strip().lstrip('/')}"
            target_state = NameObject(explicit if explicit in on_states else on_states[0])

        widget[NameObject("/V")] = target_state
        widget[NameObject("/AS")] = target_state
    else:
        text = "" if raw_value is None else str(raw_value).strip()
        max_len = widget.get("/MaxLen")
        if isinstance(max_len, int) and max_len > 0:
            text = text[:max_len]
        widget[NameObject("/V")] = TextStringObject(text)
        # Remove cached blank appearance stream so viewer synthesizes glyphs from /V + /DA
        if NameObject("/AP") in widget:
            del widget[NameObject("/AP")]


def populate_uscis_form(template_pdf: Path, field_map: dict, record: dict, out_pdf: Path) -> int:
    # Step 1: Remove owner encryption, /Perms UR3 signature lock, and hybrid /XFA array
    unlocked_tmp = out_pdf.with_suffix(".unlocked.tmp.pdf")
    with pikepdf.open(template_pdf, password="") as pdf:
        if "/Perms" in pdf.Root:
            del pdf.Root["/Perms"]
        if "/AcroForm" in pdf.Root and "/XFA" in pdf.Root.AcroForm:
            del pdf.Root.AcroForm["/XFA"]
        pdf.save(unlocked_tmp)

    # Step 2: Populate AcroForm widgets with pypdf
    reader = PdfReader(str(unlocked_tmp))
    writer = PdfWriter()
    writer.append(reader)

    root = writer._root_object
    acroform = root[NameObject("/AcroForm")].get_object()
    acroform[NameObject("/NeedAppearances")] = BooleanObject(True)

    widgets = {}
    for ref in acroform.get("/Fields", []):
        index_terminal_widgets(ref, "", widgets)

    filled_count = 0
    for canonical_key, pdf_field_path in field_map.items():
        val = record.get(canonical_key)
        if val in (None, ""):
            continue
        if pdf_field_path not in widgets:
            raise KeyError(f"Field '{pdf_field_path}' not found in {template_pdf.name}")
        set_uscis_widget_value(widgets[pdf_field_path], val)
        filled_count += 1

    out_pdf.parent.mkdir(parents=True, exist_ok=True)
    with open(out_pdf, "wb") as f:
        writer.write(f)
    unlocked_tmp.unlink(missing_ok=True)
    return filled_count


def run_batch(packet_config_path: str, csv_path: str, out_root: str) -> None:
    """
    packet_config.json structure:
    {
      "forms": {
        "G-28": {"template": "./templates/g-28.pdf", "map": {"attorney.family_name": "Pt1Line2a_FamilyName[0]", ...}},
        "I-140": {"template": "./templates/i-140.pdf", "map": {...}},
        "I-485": {"template": "./templates/i-485.pdf", "map": {...}},
        "I-765": {"template": "./templates/i-765.pdf", "map": {...}}
      }
    }
    """
    config = json.loads(Path(packet_config_path).read_text(encoding="utf-8"))
    out_dir = Path(out_root)

    with open(csv_path, newline="", encoding="utf-8-sig") as f:
        for row_idx, record in enumerate(csv.DictReader(f), start=1):
            case_id = record.get("case_id", f"case_{row_idx:03d}")
            for form_code, form_spec in config["forms"].items():
                out_file = out_dir / case_id / f"{case_id}_{form_code}.pdf"
                n = populate_uscis_form(Path(form_spec["template"]), form_spec["map"], record, out_file)
                print(f"[{case_id}] {form_code}: populated {n} fields -> {out_file}")


if __name__ == "__main__":
    if len(sys.argv) != 4:
        print("Usage: python uscis_packet_batch_filler.py packet_config.json cases.csv ./output_packets")
        sys.exit(1)
    run_batch(sys.argv[1], sys.argv[2], sys.argv[3])

4. Handling USCIS LiveCycle Input Masks & Comb Fields (`SSN`, `A-Number`, `I-94`)

When batch-filling I-129, I-140, I-485, I-765, and N-400, watch out for three field-level edge cases inside USCIS PDFs:

Comb Fields (/Ff bit 25 = 16777216 + /MaxLen): Alien Registration Numbers (A-Number, 9 digits), Social Security Numbers (9 digits), USCIS Online Account Numbers (12 digits), and ZIP codes use fixed-cell comb boxes. Strip hyphens and spaces ("A-219-847-561" -> "219847561") before writing to /V, or the characters will shift one cell to the right and clip the final digit.
LiveCycle JavaScript Validation Traps on Foreign Addresses & "Present" Dates: When opened inside Adobe Acrobat with XFA active, LiveCycle scripts validate US state codes and MM/DD/YYYY date masks—blocking common immigration entries like "PRESENT" in employment history or foreign postal codes. Stripping /AcroForm/XFA disables those rigid XFA script traps while preserving exact courier comb spacing in /AcroForm.
macOS Preview Desynchronization: If a beneficiary edits an untouched USCIS PDF in macOS Preview, Preview writes to /AcroForm /Fields /V while leaving <xfa:datasets> empty. Running the pikepdf /XFA + /Perms strip step above (or using our XFA to Fillable PDF Unlocker) immediately restores visibility in Windows Adobe Acrobat.

5. Browser & Spreadsheet Workflows for Legal Teams and HR Ops

If your immigration practice, in-house HR mobility team, or paralegal staff wants to fill single petitions or batch-generate USCIS packets from .xlsx / .csv spreadsheets without maintaining Python scripts or paying for per-seat desktop PDF licenses:

Fill PDF from Excel / CSV Batch Mail Merge: Upload any USCIS or employment form alongside an Excel or CSV roster, preview 5 populated rows for free to verify comb alignment and checkbox states, and download a ZIP archive of clean, unencrypted PDFs.
XFA to Fillable PDF Unlocker: Convert Hybrid XFA and owner-locked government PDFs into standard ISO 32000-1 AcroForm or flattened PDFs that work identically across Chrome, Safari, macOS Preview, and Windows Adobe Acrobat.
Direct Online Fillers & Field Guides for Core USCIS Packet Forms:
- Form G-28 Online Filler — Notice of Entry of Appearance as Attorney or Accredited Representative (4 pages, 101 fields)
- Form I-129 Online Filler — Petition for a Nonimmigrant Worker: H-1B, L-1, O-1, TN (38 pages, 980 fields)
- Form I-140 Online Filler — Immigrant Petition for Alien Workers: EB-1, EB-2, EB-3 (8 pages, 261 fields)
- Form I-485 Online Filler — Application to Register Permanent Residence or Adjust Status (24 pages, 760 fields)
- Form I-765 Online Filler — Application for Employment Authorization / EAD (7 pages, 161 fields)
- Form N-400 Online Filler — Application for Naturalization (14 pages, 440 fields)

Disclosure: I am the solo developer of JustFill.

AI disclosure: AI coding agents drafted and revised this article and verified the code examples above.

Why USCIS & California Court PDFs (I-765, I-485, I-130, FL-150) Open Blank After Saving in macOS Preview — And How Hybrid XFA Works

Maciej S. — Wed, 21 Oct 2026 22:22:26 +0000

Every week in immigration law firms and California family or probate practices, the same bug plays out: a client opens an official USCIS petition (Form I-765, Form I-485, or Form I-130) or a California Judicial Council court packet (FL-150, DE-111, or CM-010) on a MacBook, fills out every page in macOS Preview, saves the file, and emails it back to the paralegal.

On the client's Mac, the PDF still looks filled out. Yet the moment the paralegal opens that attachment in Adobe Acrobat Reader on Windows—or uploads it to a court Electronic Filing Service Provider (EFSP) portal—every single text box and checkbox renders 100% blank, or the portal rejects the upload with an XFA/encryption error.

This isn't user error. It is a deterministic byte-level collision between Adobe LiveCycle / AEM Forms Hybrid XFA packets, ISO 32000-1 /AcroForm widget trees, and macOS Preview's PDFKit serializer.

In our 137 Government Forms Fillability Study, we programmatically inspected 134 public government PDFs with pypdf 6.6:

85.1% (114 of 134) of government forms are Hybrid XFA (xfa_hybrid) documents containing both an /AcroForm widget hierarchy and an /XFA XML packet array.
92.3% (24 of 26) of analyzed USCIS forms (I-765, I-485, I-130, I-864, I-131, N-400) are Hybrid XFA and carry owner encryption locks (/Encrypt + /Perms), averaging a median of 227 fields across 8 pages.
76.9% (10 of 13) of California Judicial Council forms (FL-150, CM-010, DE-111, FL-100) are Hybrid XFA, and 100% (13 of 13) carry owner permission restrictions that block document assembly and flattening.

1. Inside `/Root -> /AcroForm`: How Hybrid XFA PDFs Store Data Twice

When an agency authors a form in Adobe LiveCycle Designer or AEM Forms and saves it as an "Acrobat 8 (Static) XML Form PDF," the producer writes two parallel form representations inside /Catalog -> /AcroForm:

/Fields (ISO 32000-1 §12.7 AcroForm Widget Tree): PDF dictionary objects (/Subtype /Widget, /FT /Tx or /FT /Btn) nested under form1[0].#subform[0]..., storing values in /V and glyph streams in /AP << /N ... >>.
/XFA (XML Forms Architecture Packet Array): An array of key-stream pairs (preamble, config, template, datasets, form, postamble) holding compressed XML streams.

Inspecting /Catalog -> /AcroForm inside USCIS Form I-765 (7 pages, 161 fields) or California FL-150 (4 pages, 262 fields) reveals both structures side by side:

1 0 obj
<<
  /Type /Catalog
  /Pages 3 0 R
  /Perms << /UR3 4 0 R >>
  /AcroForm <<
    /Fields [ 12 0 R ]
    /DA (/CourierStd 10 Tf 0 g)
    /XFA [
      (preamble)  15 0 R  (config)    16 0 R
      (template)  17 0 R  (datasets)  18 0 R
      (form)      19 0 R  (postamble) 20 0 R
    ]
  >>
>>
endobj

Stream 18 0 R (datasets) stores the <xfa:datasets> XML tree read by XFA-aware viewers:

<xfa:datasets xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/">
  <xfa:data>
    <form1><Page1><Pt1Line1a_FamilyName/><Pt1Line1b_GivenName/></Page1></form1>
  </xfa:data>
</xfa:datasets>

Meanwhile, the corresponding AcroForm widget dictionary inside /Fields represents the same input box for non-XFA viewers:

245 0 obj
<< /Type /Annot /Subtype /Widget /FT /Tx /T (Pt1Line1a_FamilyName[0])
   /TU (Part 1. Line 1a. Family Name (Last Name))
   /Rect [ 54.00 582.10 294.00 596.50 ] /V () /AP << /N 246 0 R >> >>
endobj

2. Why macOS Preview Saves Open Blank in Windows Adobe Acrobat

Apple's macOS Preview (PDFKit) does not implement an XFA XML parser. When a user fills and saves a Hybrid XFA PDF in Preview:

Preview ignores /XFA: It renders and edits only the /AcroForm -> /Fields widget tree.
Preview writes user input only into /AcroForm /Fields /V: Typing into Pt1Line1a_FamilyName[0] writes /V (Smith) in the PDF incremental update trailer while leaving stream 18 0 R (<xfa:datasets>) untouched and empty (<Pt1Line1a_FamilyName/>).
Preview often omits or corrupts portable /AP /N appearance streams: Preview writes Apple font references or alters /NeedAppearances while leaving the /XFA key intact inside /AcroForm.

When Adobe Acrobat Reader on Windows opens a hybrid PDF that still contains /XFA, Acrobat's XFA runtime takes precedence over /AcroForm /Fields /V:

Does /Root/AcroForm contain an /XFA key?
 ├── YES -> Adobe Acrobat loads stream 18 0 R (<xfa:datasets>)
 │          Ignores /AcroForm /Fields /V ("Smith")
 │          Renders empty <xfa:datasets> XML -> 100% BLANK FIELDS
 └── NO  -> Standard ISO 32000-1 renderer reads /AcroForm /Fields /V
            All typed values render normally

Worse: if a paralegal clicks Save in Acrobat while that blank XFA view is open, Acrobat overwrites /AcroForm /Fields /V with the empty <xfa:datasets> state—permanently erasing the client's answers.

3. Recovering "Blank" Preview PDFs & Stripping `/XFA` + `/Perms` in Python

Before re-saving a client's PDF in Acrobat, you can extract every /V value saved by macOS Preview, strip the stale /XFA packet and /Perms usage-rights lock, and regenerate appearance streams using pikepdf and pypdf:

#!/usr/bin/env python3
"""Recover macOS Preview edits from Hybrid XFA PDFs and strip /XFA + /Perms locks."""
import json, sys
from pathlib import Path
import pikepdf
from pypdf import PdfReader, PdfWriter
from pypdf.generic import BooleanObject, NameObject

def walk_values(node_ref, prefix="", out=None):
    out = {} if out is None else out
    node = node_ref.get_object()
    name = str(node.get("/T", ""))
    full = f"{prefix}.{name}" if prefix and name else (name or prefix)
    if "/Kids" in node:
        for kid in node["/Kids"]:
            walk_values(kid, full, out)
    elif node.get("/V") not in (None, "", "/Off"):
        out[full] = str(node.get("/V"))
    return out

def normalize_hybrid_pdf(input_pdf: str, output_pdf: str) -> dict:
    tmp = Path(output_pdf).with_suffix(".tmp.pdf")
    with pikepdf.open(input_pdf, password="") as pdf:
        if "/Perms" in pdf.Root:
            del pdf.Root["/Perms"]
        if "/AcroForm" in pdf.Root and "/XFA" in pdf.Root.AcroForm:
            del pdf.Root.AcroForm["/XFA"]
        pdf.save(tmp)

    reader = PdfReader(str(tmp))
    writer = PdfWriter()
    writer.append(reader)
    acroform = writer._root_object[NameObject("/AcroForm")].get_object()
    acroform[NameObject("/NeedAppearances")] = BooleanObject(True)

    recovered = {}
    for ref in acroform.get("/Fields", []):
        recovered.update(walk_values(ref))

    for page in writer.pages:
        for annot_ref in page.get("/Annots", []):
            annot = annot_ref.get_object()
            if annot.get("/Subtype") == "/Widget" and annot.get("/FT") == "/Tx":
                if annot.get("/V") and NameObject("/AP") in annot:
                    del annot[NameObject("/AP")]

    with open(output_pdf, "wb") as f:
        writer.write(f)
    tmp.unlink(missing_ok=True)
    return recovered

if __name__ == "__main__":
    recovered = normalize_hybrid_pdf(sys.argv[1], sys.argv[2])
    print(f"Recovered {len(recovered)} fields:", json.dumps(recovered, indent=2))

Note why deleting /Root/Perms alongside /AcroForm/XFA is mandatory: USCIS and California court PDFs include an Adobe /UR3 usage-rights signature inside /Perms. If you strip /XFA without removing /Perms, Acrobat detects a modified byte digest and blocks saving.

4. Audited USCIS & California Court Forms & Browser Workflows

Form Code	Agency	Pages	Audited Fields	Hybrid `/XFA`	Owner `/Encrypt`
Form I-765	USCIS	7	161 (`119 Tx`, `38 Btn`, `4 Ch`)	Yes	Yes
Form I-130	USCIS	12	450 (`302 Tx`, `128 Btn`, `20 Ch`)	Yes	Yes
Form I-485	USCIS	24	760 (`334 Tx`, `416 Btn`, `10 Ch`)	Yes	Yes
Form FL-150	CA Judicial Council	4	262 (`212 Tx`, `50 Btn`)	Yes	Yes
Form CM-010	CA Judicial Council	3	84 (`23 Tx`, `61 Btn`)	Yes	Yes
Form DE-111	CA Judicial Council	4	Probate Petition (`Tx` + `Btn`)	Yes	Yes

If you want clients or legal staff to complete these forms in Chrome, Safari, Edge, or Firefox on macOS or Windows without triggering the macOS Preview /XFA blank-fields bug—or convert locked XFA files into clean AcroForm or flattened PDFs—use these tools and audited guides:

XFA to Fillable PDF Unlocker: Strip /XFA and owner locks from DD-2875, FL-150, DE-111, CM-010, I-765, or I-485 and export standard AcroForm or flattened PDFs.
USCIS Form I-765 Online Filler & Mac Preview Fix: Fill all 7 pages and 161 fields of the Employment Authorization application online with baked appearance streams.
USCIS Form I-130 Online Petition Filler: Complete the 12-page, 450-field Petition for Alien Relative without LiveCycle input mask blocks on foreign addresses.
USCIS Form I-485 Adjustment of Status Filler: Fill the 24-page, 760-field Adjustment of Status packet across Mac and Windows without losing field data.
California FL-150 Income and Expense Declaration: Complete the 4-page, 262-field California family law financial disclosure (FL-150) alongside CM-010 and DE-111 and export flattened PDFs for court EFSP e-filing.
137 Government Forms Fillability Study: Full structural dataset of /AcroForm, /XFA, /Encrypt, and /TU semantics across 134 government PDFs.

Disclosure: I am the solo developer of JustFill.

AI disclosure: AI coding agents drafted and revised this article and verified the code examples above.

How to Mail Merge from Excel (.xlsx / CSV) into Official IRS & ACA PDFs (1095-C, W-9, Form 2848, SS-4) Without Adobe Acrobat

Maciej S. — Wed, 21 Oct 2026 19:08:56 +0000

Every January through March, engineering teams, payroll ops, and accounting practices hit the same wall: a spreadsheet with 50 to 500 rows of employee or entity records in .xlsx or .csv format, and an official IRS PDF template (f1095c.pdf, fw9.pdf, f2848.pdf, fss4.pdf, or f843.pdf) that needs one populated PDF generated per row.

If you open an official IRS PDF in a standard Python script and try to map column employee_ssn to a field named "employee_ssn", zero fields match. Even worse, if you guess the field name and write {"c1_1[0]": "Yes"} to a checkbox, the generated PDF opens in macOS Preview or Chrome with an unchecked box.

Below is a technical breakdown of how official IRS PDFs are structured under the hood, why their /AcroForm trees and /XFA streams break naive mail-merge scripts, and a complete Python implementation for deterministic CSV/Excel-to-PDF batch generation.

1. Why Official IRS PDFs Break Naive Mail-Merge Scripts

Official IRS forms are authored in Adobe LiveCycle Designer / AEM Forms and exported as hybrid AcroForm documents. That authoring pipeline introduces four specific pitfalls:

Pitfall A: Hierarchical Subform Paths and Positional `/T` Keys

Instead of semantic field names like employee_first_name, LiveCycle nests every widget inside topmostSubform[0] -> Page1[0] -> subform containers, with terminal /T keys named f1_1[0], f1_2[0], ..., f1_68[0] (for text inputs) and c1_1[0], c1_2[0] (for checkboxes).

Fortunately, the IRS embeds the human-readable instructions inside each field dictionary's /TU (Alternate Field Name / Tooltip) entry. Here is what a single field dictionary inside f1095c.pdf actually looks like:

42 0 obj
<<
  /Type /Annot
  /Subtype /Widget
  /FT /Tx
  /Parent 38 0 R
  /T (f1_1[0])
  /TU (Part I, Line 1. Employee first name and middle initial)
  /Rect [ 36.00 662.40 165.60 676.80 ]
  /MaxLen 35
  /DA (/MyriadPro-Regular 9 Tf 0 g)
>>
endobj

When you walk the /AcroForm/Fields tree recursively, joining /Parent names with . gives the full qualified name topmostSubform[0].Page1[0].EmployeeName[0].f1_1[0], while /TU tells you what spreadsheet column actually belongs there.

Pitfall B: Hybrid `/XFA` Streams Overriding `/AcroForm` Values

Many government PDFs contain both a standard /AcroForm/Fields array and an /XFA XML packet stream inside /Catalog/AcroForm. When a viewer that supports XFA (such as Adobe Acrobat Reader) opens the file, it prioritizes the /XFA <datasets><xfa:data> XML over the /AcroForm /V entries. If your script only updates /AcroForm /V without stripping the /XFA key from /AcroForm (or updating both), Acrobat displays blank fields even though Chrome PDFium and pypdf show the filled values.

Pitfall C: Checkbox `/AS` Appearance States (`/1` vs. `/Yes`)

In ISO 32000-1 §12.7.4.2, a checkbox (/FT /Btn without the radio or pushbutton bit flags) stores its visual glyph streams inside /AP << /N << ... >> >>. While custom PDFs often name the checked state /Yes, IRS forms almost universally use /1 or /2 as the checked NameObject key, and /Off for unchecked:

% Checkbox widget appearance dictionary in IRS Form 2848 / Form 1095-C
/AP <<
  /N <<
    /1 89 0 R
    /Off 90 0 R
  >>
>>
/V /Off
/AS /Off

If you set /V to "Yes" or TextStringObject("1") instead of inspecting /AP/N and setting both /V and /AS to NameObject("/1"), the checkbox remains visually blank.

2. Inspecting IRS AcroForm Schemas (`1095-C`, `2848`, `SS-4`, `843`)

Before writing a single value from Excel or CSV, run an inspection pass that extracts every terminal widget's full path, /FT type, /TU tooltip, page index, /Rect coordinates, and valid /AP/N appearance keys.

#!/usr/bin/env python3
"""
dump_irs_schema.py
Extract full AcroForm field paths, tooltips (/TU), bounding boxes (/Rect),
and valid checkbox appearance states (/AP/N) from any IRS PDF.
"""

import json
import sys
from pypdf import PdfReader


def walk_fields(node_ref, prefix="", out=None):
    if out is None:
        out = []
    node = node_ref.get_object()
    local_name = str(node.get("/T", ""))
    full_name = f"{prefix}.{local_name}" if prefix and local_name else (local_name or prefix)

    kids = node.get("/Kids")
    if kids:
        for kid_ref in kids:
            walk_fields(kid_ref, full_name, out)
        return out

    ft = str(node.get("/FT", ""))
    tu = str(node.get("/TU", ""))
    rect = [float(x) for x in node.get("/Rect", [])]

    ap_states = []
    ap = node.get("/AP")
    if ap and "/N" in ap.get_object():
        normal_ap = ap.get_object()["/N"].get_object()
        if hasattr(normal_ap, "keys"):
            ap_states = [str(k) for k in normal_ap.keys()]

    out.append({
        "full_name": full_name,
        "short_name": local_name,
        "type": ft,
        "tooltip": tu,
        "rect": rect,
        "checked_states": [s for s in ap_states if s != "/Off"],
    })
    return out


def main(pdf_path: str) -> None:
    reader = PdfReader(pdf_path)
    acroform = reader.trailer["/Root"].get_object().get("/AcroForm")
    if not acroform:
        raise RuntimeError(f"No /AcroForm found in {pdf_path}")

    fields = []
    for ref in acroform.get_object().get("/Fields", []):
        walk_fields(ref, "", fields)

    print(json.dumps(fields, indent=2))


if __name__ == "__main__":
    main(sys.argv[1])

Running dump_irs_schema.py against the four most common compliance and tax onboarding forms reveals how their schemas map to spreadsheet columns:

IRS Form	Primary Batch Use Case	Example AcroForm `/T` Terminal Keys	Key Formatting Gotcha
Form 1095-C	ACA Employer-Provided Health Insurance Offer & Coverage	`f1_1[0]`..`f1_13[0]` (Part I Employee/ALE info), `f1_14[0]`..`f1_26[0]` (Line 14 Offer codes `1A`–`1U`), `f1_27[0]`..`f1_39[0]` (Line 15 dollar amounts), `f1_40[0]`..`f1_52[0]` (Line 16 Safe Harbor `2A`–`2I`)	Line 15 requires cents (`142.50`, not `$142.50`). If `"All 12 Months"` (`f1_14[0]`) is populated, Jan–Dec (`f1_15[0]`..`f1_26[0]`) must remain blank.
Form 2848	Power of Attorney and Declaration of Representative	`f1_01[0]` (Taxpayer identification block), `f1_02[0]` (TIN), `f1_04[0]`..`f1_12[0]` (Representative CAF No., PTIN, tel), `f1_22[0]`..`f1_30[0]` (Line 3 Income/Employment tax matters & years)	Line 3 columns are split strictly into Description of Matter (`Income, Employment, Payroll`), Tax Form Number (`941, 1120`), and Year(s) or Period(s).
Form SS-4	Application for Employer Identification Number (EIN)	`f1_1[0]` (Legal name of entity), `f1_2[0]` (Trade name), `f1_7[0]` (Responsible party name), `f1_8[0]` (SSN/ITIN/EIN), `c1_1[0]`..`c1_15[0]` (Line 9a Entity Type checkboxes)	Line 9a checkboxes use `/1` as their checked appearance state; LLC member count (`f1_17[0]`) and state (`f1_18[0]`) are separate narrow boxes.
Form 843	Claim for Refund and Request for Abatement	`f1_1[0]` (Name), `f1_2[0]` (SSN/EIN), `f1_7[0]`..`f1_8[0]` (Tax period dates), `f1_9[0]` (Amount to be refunded/abated), `c1_1[0]`..`c1_6[0]` (Line 3 type of tax/fee), `f1_14[0]` (Line 7 Reasonable Cause explanation)	Line 7 (`f1_14[0]`) has `/Ff 4096` (Multiline) enabled, but overflow text beyond the box height shrinks or clips unless line breaks are normalized.

If you want to inspect or fill individual forms in the browser before automating a batch, you can open the batch-fill IRS Form 1095-C for ACA reporting workspace, prepare a fillable IRS Form 2848 Power of Attorney for client authorizations, complete an online Form SS-4 EIN application for new LLC formations, or draft an IRS Form 843 penalty abatement request directly online.

3. Structuring the CSV / Excel Input (`aca_1095c_batch.csv`)

Never map spreadsheet columns by positional index (col[0], col[1]). A single reordered column in Excel will silently write an employee's SSN into the wrong Part I box. Instead, define a strict column-to-AcroForm mapping file (1095c_mapping.json) and validate every header before filling row 1.

Here is a sample aca_1095c_batch.csv for two employees (all values synthetic):

employee_id,emp_first_name,emp_middle_initial,emp_last_name,emp_ssn,ale_name,ale_ein,ale_contact_phone,plan_start_month,line14_all12,line15_all12,line16_all12,part3_covered_ind
EMP_001,Maya,J,Lin,900-00-0001,Northwind Logistics LLC,00-0000001,555-010-0192,01,1E,138.50,2G,false
EMP_002,Carlos,M,Rivera,900-00-0002,Northwind Logistics LLC,00-0000001,555-010-0192,01,1A,0.00,2C,true

And the corresponding deterministic mapping configuration (1095c_mapping.json):

{
  "output_pattern": "1095C_{employee_id}_{emp_last_name}.pdf",
  "strip_xfa": true,
  "fields": {
    "emp_first_name": "f1_1[0]",
    "emp_middle_initial": "f1_2[0]",
    "emp_last_name": "f1_3[0]",
    "emp_ssn": "f1_4[0]",
    "ale_name": "f1_9[0]",
    "ale_ein": "f1_10[0]",
    "ale_contact_phone": "f1_12[0]",
    "plan_start_month": "f1_13[0]",
    "line14_all12": "f1_14[0]",
    "line15_all12": "f1_27[0]",
    "line16_all12": "f1_40[0]",
    "part3_covered_ind": "c1_1[0]"
  }
}

4. Deterministic Python Batch Mail-Merge Script (`csv` / `.xlsx` → IRS PDFs)

The script below loads the IRS PDF template once per row, strips any conflicting /XFA entry so /AcroForm values are authoritative across all PDF viewers, sets /NeedAppearances to true, and writes both text fields (/Tx) and checkboxes (/Btn with /AP/N state inspection):

#!/usr/bin/env python3
"""
batch_fill_irs_pdf.py
Deterministic CSV/Excel mail merge into official IRS AcroForm PDFs.
Requires: pip install pypdf
"""

import csv
import json
import sys
from pathlib import Path
from pypdf import PdfReader, PdfWriter
from pypdf.generic import BooleanObject, NameObject, TextStringObject


def index_terminal_widgets(acroform_obj) -> dict:
    """Map terminal /T names (e.g., 'f1_1[0]') and full paths to widget dicts."""
    by_name = {}

    def walk(ref, prefix=""):
        node = ref.get_object()
        t_val = str(node.get("/T", ""))
        full = f"{prefix}.{t_val}" if prefix and t_val else (t_val or prefix)
        kids = node.get("/Kids")
        if kids:
            for kid in kids:
                walk(kid, full)
            return
        if t_val:
            by_name[t_val] = node
        if full:
            by_name[full] = node

    for root_ref in acroform_obj.get("/Fields", []):
        walk(root_ref)
    return by_name


def detect_checked_name(widget) -> NameObject:
    """Inspect /AP/N to find the exact checked state name (e.g., /1 or /Yes)."""
    ap = widget.get("/AP")
    if ap and "/N" in ap.get_object():
        normal = ap.get_object()["/N"].get_object()
        if hasattr(normal, "keys"):
            for key in normal.keys():
                if str(key) != "/Off":
                    return NameObject(str(key))
    return NameObject("/1")


def set_widget_value(widget, raw_value: str) -> None:
    ft = str(widget.get("/FT", ""))
    if not ft and "/Parent" in widget:
        ft = str(widget["/Parent"].get_object().get("/FT", ""))

    if ft == "/Btn":
        truthy = str(raw_value).strip().lower() in {"1", "true", "yes", "x", "checked"}
        state = detect_checked_name(widget) if truthy else NameObject("/Off")
        widget[NameObject("/V")] = state
        widget[NameObject("/AS")] = state
    else:
        text = "" if raw_value is None else str(raw_value).strip()
        widget[NameObject("/V")] = TextStringObject(text)
        if NameObject("/AP") in widget:
            # Force viewer to regenerate glyph stream from /V + /DA
            del widget[NameObject("/AP")]


def fill_single_row(template_pdf: str, mapping: dict, row: dict, out_dir: Path) -> Path:
    reader = PdfReader(template_pdf)
    writer = PdfWriter()
    writer.append(reader)

    root = writer._root_object
    acroform = root[NameObject("/AcroForm")].get_object()

    if mapping.get("strip_xfa", True) and NameObject("/XFA") in acroform:
        del acroform[NameObject("/XFA")]

    acroform[NameObject("/NeedAppearances")] = BooleanObject(True)
    widgets = index_terminal_widgets(acroform)

    for col_name, target_field in mapping["fields"].items():
        if col_name not in row:
            raise KeyError(f"Missing required CSV column: {col_name}")
        if target_field not in widgets:
            raise KeyError(f"PDF field '{target_field}' not found in {template_pdf}")
        set_widget_value(widgets[target_field], row[col_name])

    filename = mapping["output_pattern"].format(**row)
    out_path = out_dir / filename
    with open(out_path, "wb") as f:
        writer.write(f)
    return out_path


def main(template_pdf: str, mapping_json: str, csv_path: str, out_dir_str: str) -> None:
    mapping = json.loads(Path(mapping_json).read_text(encoding="utf-8"))
    out_dir = Path(out_dir_str)
    out_dir.mkdir(parents=True, exist_ok=True)

    with open(csv_path, newline="", encoding="utf-8-sig") as f:
        reader = csv.DictReader(f)
        for idx, row in enumerate(reader, start=1):
            out_path = fill_single_row(template_pdf, mapping, row, out_dir)
            print(f"[{idx}] Generated {out_path}")


if __name__ == "__main__":
    if len(sys.argv) != 5:
        print("Usage: python batch_fill_irs_pdf.py template.pdf mapping.json data.csv ./output")
        sys.exit(1)
    main(sys.argv[1], sys.argv[2], sys.argv[3], sys.argv[4])

Why `del widget[NameObject("/AP")]` Matters for Text Inputs

When an IRS PDF is saved with pre-existing blank appearance streams (/AP << /N ... >>) on text fields, updating /V alone can leave PDF.js or macOS Preview rendering the cached empty /AP/N stream instead of your new string. Deleting /AP on modified /Tx widgets while setting /NeedAppearances true on /AcroForm forces the viewer to synthesize a fresh appearance stream from /V and /DA. (For checkboxes /Btn, however, you must keep /AP intact because /AP/N holds the vector checkmark glyph!)

5. Browser-Based Mail Merge When You Don't Want to Maintain Field Maps

Maintaining f1_14[0]..f1_52[0] JSON lookup tables makes sense when you are embedding PDF generation inside a backend microservice. When an accounting, HR, or operations team simply has an .xlsx or .csv file and needs filled PDFs without writing Python or buying Adobe Acrobat Pro seats:

You can run a mail merge from Excel to a fillable PDF or use the PDF mail merge from CSV or Excel workflow to upload any fillable PDF alongside a spreadsheet, visually review the matched column-to-field mappings (including a free 5-row sample preview to verify alignment before running a full batch), and download a ZIP archive of individually named PDFs.
For multi-client tax and compliance practices handling recurring authorizations, EIN applications, and year-end filings, see our PDF form automation for bookkeepers and CPAs overview (or check the Excel-to-PDF batch workflow guide).

6. Pre-Flight Validation Checklist Before Generating 100+ Tax Forms

Before running a production batch of 1095-C, W-9, 2848, or SS-4 forms:

Encoding Check (utf-8-sig): Excel's "Save as CSV (UTF-8)" prepends a 3-byte UTF-8 Byte Order Mark (\xef\xbb\xbf). Always open CSV files with encoding="utf-8-sig" in Python so the first column header is parsed as "employee_id" rather than "\ufeffemployee_id".
Leading Zero Preservation: EINs (01-2345678), SSNs, and New England ZIP codes (02110) lose their leading zeros if Excel auto-formats the column as General or Number. Format TIN/ZIP columns as Text before exporting, or left-pad ZIP codes (str(zip_code).zfill(5)) in your ingestion step.
5-Row Visual Spot Check: Always inspect the first 5 generated PDFs across at least two independent renderers (e.g., Chrome PDFium and macOS Preview / Adobe Reader) to verify that long entity names do not clip on /MaxLen boundaries and that every checkbox /AS state renders visibly.

Disclosure: I am the solo developer of JustFill.

AI disclosure: AI coding agents drafted and revised this article and verified the code examples above.

Why Exporting Word (.docx) to PDF Strips Form Fields (And How AcroForm Widget Reconstruction Works)

Maciej S. — Wed, 21 Oct 2026 19:08:43 +0000

If you build an intake form, contract template, or HR onboarding sheet in Microsoft Word using Developer → Content Controls (Plain Text, Check Box, Combo Box, or Date Picker) and export it via File → Save As → PDF or Microsoft Print to PDF, the resulting PDF looks right on screen—until someone tries to type into it.

Every text box, checkbox, and underline is dead geometry. If you inspect the PDF's root /Catalog dictionary, /AcroForm is completely absent.

This post explains what actually happens inside the OOXML-to-PDF conversion pipeline, how ISO 32000-1 interactive form dictionaries (/AcroForm and /Subtype /Widget annotations) differ from page content streams, and how to programmatically reconstruct interactive fields from a flattened Word PDF using Python (pypdf) or browser-based layout tools.

1. What Word Stores in `.docx` vs. What Lands in the PDF Stream

A .docx archive is a ZIP container of Open Packaging Conventions (OPC) XML files. When you insert modern Content Controls in Word, they are stored inside word/document.xml as <w:sdt> (Structured Document Tag) elements:

<!-- word/document.xml inside the .docx ZIP archive -->
<w:sdt>
  <w:sdtPr>
    <w:alias w:val="Applicant Full Name"/>
    <w:tag w:val="applicant_full_name"/>
    <w:id w:val="104829104"/>
    <w:text/>
  </w:sdtPr>
  <w:sdtContent>
    <w:p>
      <w:r>
        <w:t>_________________________</w:t>
      </w:r>
    </w:p>
  </w:sdtContent>
</w:sdt>

<w:sdt>
  <w:sdtPr>
    <w:alias w:val="US Citizen"/>
    <w:tag w:val="is_us_citizen"/>
    <w:lcid w:val="0409"/>
    <w14:checkbox>
      <w14:checked w14:val="0"/>
      <w14:checkedState w14:val="2612" w14:font="MS Gothic"/>
      <w14:uncheckedState w14:val="2610" w14:font="MS Gothic"/>
    </w14:checkbox>
  </w:sdtPr>
  <w:sdtContent>
    <w:r>
      <w:t>☐</w:t>
    </w:r>
  </w:sdtContent>
</w:sdt>

Notice what happens during Word's native PDF export:

Print-driver architecture: Microsoft Print to PDF routes the document through the Windows XPS/GDI print subsystem, which only understands visual glyph runs, vector paths, and raster bitmaps. Semantic tags like <w:sdtPr> and <w:tag> are discarded before the PDF writer ever sees the page.
Built-in Exporter (Save As PDF): Even when "Document structure tags for accessibility" is enabled, Word maps <w:sdtContent> into the /StructTreeRoot tagged-PDF tree as standard <P> or <Span> nodes—not interactive /Annot objects.
Visual fallback: The placeholder underscores (_____) or Unicode ballot box (U+2610 ☐) inside <w:sdtContent> are emitted directly into the page's /Contents stream as raw PostScript-style drawing operators:

BT
  /F1 11 Tf
  72.00 684.50 Td
  (Applicant Full Name: _________________________) Tj
ET

At that point, the PDF viewer only sees static text operators (BT ... Tj ET) or vector line segments (m, l, S). There is nothing in the PDF object graph for a user to focus or type into.

2. Anatomy of a Real Fillable PDF (`/AcroForm` + `/Widget` Annotations)

In ISO 32000-1 (PDF 1.7, §12.7), interactive form fields do not live inside the page's /Contents drawing stream. Instead, they require two linked structures in the PDF cross-reference table:

The Document-Level /AcroForm Dictionary (attached to the /Catalog root object):
- /Fields: An array of indirect object references ([ 15 0 R 16 0 R ... ]) pointing to the root fields of the document.
- /NeedAppearances: A boolean (true) instructing the viewer to regenerate visual glyph streams when field values change, or /DR (Default Resources) providing /Font dictionaries (/Helv, /ZaDb) for appearance generation.
Page-Level /Subtype /Widget Annotations (referenced in each page's /Annots array):
- In most single-widget AcroForm fields, the field dictionary and the widget annotation dictionary are merged into a single PDF object.

Here is what a valid interactive text field and checkbox actually look like in raw PDF syntax:

% Root Catalog
1 0 obj
<<
  /Type /Catalog
  /Pages 2 0 R
  /AcroForm <<
    /Fields [ 15 0 R 16 0 R ]
    /NeedAppearances true
    /DA (/Helv 10 Tf 0 g)
    /DR <<
      /Font <<
        /Helv << /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>
        /ZaDb << /Type /Font /Subtype /Type1 /BaseFont /ZapfDingbats >>
      >>
    >>
  >>
>>
endobj

% Merged Field + Widget Annotation for a Text Input
15 0 obj
<<
  /Type /Annot
  /Subtype /Widget
  /FT /Tx
  /P 3 0 R
  /T (applicant_full_name)
  /TU (Applicant Full Name)
  /V ()
  /DV ()
  /Ff 0
  /Rect [ 185.0 682.0 410.0 698.0 ]
  /DA (/Helv 10 Tf 0 0 0 rg)
>>
endobj

% Merged Field + Widget Annotation for a Checkbox
16 0 obj
<<
  /Type /Annot
  /Subtype /Widget
  /FT /Btn
  /P 3 0 R
  /T (is_us_citizen)
  /TU (US Citizen)
  /V /Off
  /AS /Off
  /Ff 0
  /Rect [ 185.0 654.0 197.0 666.0 ]
  /DA (/ZaDb 10 Tf 0 g)
>>
endobj

Key Dictionary Keys Engineers Need to Know

Key	Type	Meaning in ISO 32000-1 §12.7
`/FT`	Name	Field Type: `/Tx` (Text), `/Btn` (Button: checkbox, radio, pushbutton), `/Ch` (Choice: dropdown/listbox), `/Sig` (Signature).
`/T`	String	Partial field name (`applicant_full_name`). Period-delimited names (`applicant.name`) are formed by `/Parent` / `/Kids` hierarchies.
`/TU`	String	Alternate field name displayed as a tooltip and announced by screen readers.
`/Rect`	Array	`[llx lly urx ury]` in default user space units (1/72 inch points), with origin `(0, 0)` at the bottom-left corner of the page `/MediaBox`.
`/Ff`	Integer	32-bit field flags bitmask. Bit 1 (`1`): ReadOnly; Bit 2 (`2`): Required; Bit 13 (`4096`): Multiline text; Bit 16 (`32768`): Radio button; Bit 17 (`65536`): Pushbutton.
`/V` & `/AS`	Any / Name	`/V` holds the field's value; `/AS` holds the active Appearance State name (e.g., `/Yes` or `/Off` for checkboxes) selecting which stream in `/AP << /N << ... >> >>` to render.

If you want to quickly verify whether a PDF exported from Word or LibreOffice actually contains /AcroForm entries or was flattened into static vectors, you can inspect PDF AcroForm fields in the browser to view its /Fields count, field types, and names without uploading it to an external server.

3. Coordinate Space Mismatch: DOM/Word Top-Left vs. PDF Bottom-Left

When reconstructing widgets on top of a flattened Word PDF, the most common bug is vertical inversion.

Word / HTML Canvas / Browser DOM: Origin (0, 0) is at the top-left of the page. A box at (x, y) with width w and height h extends downward.
PDF User Space (/MediaBox): Origin (0, 0) is at the bottom-left of the page (unless /Rotate is 90, 180, or 270). A standard US Letter page has /MediaBox [0 0 612 792].

To convert a bounding box detected in top-left screen coordinates (x_top, y_top, width, height) (measured at 72 DPI scale) into a PDF /Rect [llx, lly, urx, ury]:

def dom_box_to_pdf_rect(
    x_top: float,
    y_top: float,
    width: float,
    height: float,
    page_height: float = 792.0,
) -> list[float]:
    """
    Convert a top-left origin bounding box (x, y, w, h) into an ISO 32000-1
    bottom-left origin PDF /Rect [llx, lly, urx, ury].
    """
    llx = round(x_top, 2)
    ury = round(page_height - y_top, 2)
    urx = round(x_top + width, 2)
    lly = round(page_height - (y_top + height), 2)
    return [llx, lly, urx, ury]

If the page has a non-zero /Rotate entry in its page dictionary (common when scanned pages or landscape tables are merged into a Word export), you must also apply the inverse rotation matrix before writing /Rect, or set the annotation's /MK << /R 90 >> appearance characteristics dictionary so the text baseline aligns with the visual text run.

4. Reconstructing AcroForm Widgets in Python (`pypdf`)

Suppose you have a flattened PDF exported from Word (onboarding_flattened.pdf) and a JSON field manifest defining where the interactive widgets belong—either extracted from the .docx layout, detected via OCR/line-segment heuristics, or mapped once in a visual editor.

Here is a sample fields_manifest.json:

[
  {
    "page": 0,
    "name": "applicant_full_name",
    "tooltip": "Applicant Full Name",
    "type": "text",
    "multiline": false,
    "rect_top_left": { "x": 185.0, "y": 94.0, "width": 225.0, "height": 16.0 }
  },
  {
    "page": 0,
    "name": "employment_history_summary",
    "tooltip": "Employment History Summary (Past 5 Years)",
    "type": "text",
    "multiline": true,
    "rect_top_left": { "x": 72.0, "y": 140.0, "width": 468.0, "height": 64.0 }
  },
  {
    "page": 0,
    "name": "is_us_citizen",
    "tooltip": "U.S. Citizen",
    "type": "checkbox",
    "rect_top_left": { "x": 185.0, "y": 126.0, "width": 12.0, "height": 12.0 }
  }
]

And here is a complete, dependency-light Python script using pypdf that constructs the /AcroForm dictionary, registers default font resources (/Helv and /ZaDb), creates /Subtype /Widget annotations with proper /Ff bitmasks, and attaches them to both the page /Annots array and /Catalog/AcroForm/Fields:

#!/usr/bin/env python3
"""
reconstruct_acroform.py
Inject interactive AcroForm /Widget annotations into a flattened Word-exported PDF.
Requires: pip install pypdf
"""

import json
import sys
from pathlib import Path
from pypdf import PdfReader, PdfWriter
from pypdf.generic import (
    ArrayObject,
    BooleanObject,
    DictionaryObject,
    FloatObject,
    NameObject,
    NumberObject,
    TextStringObject,
)

FF_MULTILINE = 1 << 12  # Bit 13 (4096) in 1-indexed ISO 32000-1 spec


def ensure_acroform(writer: PdfWriter) -> DictionaryObject:
    root = writer._root_object
    if NameObject("/AcroForm") not in root:
        helv_font = DictionaryObject({
            NameObject("/Type"): NameObject("/Font"),
            NameObject("/Subtype"): NameObject("/Type1"),
            NameObject("/BaseFont"): NameObject("/Helvetica"),
        })
        zadb_font = DictionaryObject({
            NameObject("/Type"): NameObject("/Font"),
            NameObject("/Subtype"): NameObject("/Type1"),
            NameObject("/BaseFont"): NameObject("/ZapfDingbats"),
        })
        acroform = DictionaryObject({
            NameObject("/Fields"): ArrayObject(),
            NameObject("/NeedAppearances"): BooleanObject(True),
            NameObject("/DA"): TextStringObject("/Helv 10 Tf 0 g"),
            NameObject("/DR"): DictionaryObject({
                NameObject("/Font"): DictionaryObject({
                    NameObject("/Helv"): writer._add_object(helv_font),
                    NameObject("/ZaDb"): writer._add_object(zadb_font),
                })
            }),
        })
        root[NameObject("/AcroForm")] = writer._add_object(acroform)
    return root[NameObject("/AcroForm")].get_object()


def add_widget(writer: PdfWriter, spec: dict) -> None:
    acroform = ensure_acroform(writer)
    page = writer.pages[spec["page"]]
    page_height = float(page.mediabox.height)

    box = spec["rect_top_left"]
    llx = box["x"]
    ury = page_height - box["y"]
    urx = box["x"] + box["width"]
    lly = page_height - (box["y"] + box["height"])

    rect = ArrayObject([
        FloatObject(round(llx, 2)),
        FloatObject(round(lly, 2)),
        FloatObject(round(urx, 2)),
        FloatObject(round(ury, 2)),
    ])

    is_checkbox = spec.get("type") == "checkbox"
    ff_flags = FF_MULTILINE if spec.get("multiline") else 0

    widget = DictionaryObject({
        NameObject("/Type"): NameObject("/Annot"),
        NameObject("/Subtype"): NameObject("/Widget"),
        NameObject("/FT"): NameObject("/Btn" if is_checkbox else "/Tx"),
        NameObject("/P"): page.indirect_reference,
        NameObject("/T"): TextStringObject(spec["name"]),
        NameObject("/TU"): TextStringObject(spec.get("tooltip", spec["name"])),
        NameObject("/Rect"): rect,
        NameObject("/F"): NumberObject(4),  # Print flag (bit 3) so filled values print
        NameObject("/Ff"): NumberObject(ff_flags),
        NameObject("/DA"): TextStringObject(
            "/ZaDb 10 Tf 0 g" if is_checkbox else "/Helv 10 Tf 0 0 0 rg"
        ),
    })

    if is_checkbox:
        widget[NameObject("/V")] = NameObject("/Off")
        widget[NameObject("/AS")] = NameObject("/Off")
    else:
        widget[NameObject("/V")] = TextStringObject("")
        widget[NameObject("/DV")] = TextStringObject("")

    widget_ref = writer._add_object(widget)

    if NameObject("/Annots") not in page:
        page[NameObject("/Annots")] = ArrayObject()
    page[NameObject("/Annots")].append(widget_ref)
    acroform[NameObject("/Fields")].append(widget_ref)


def main(input_pdf: str, manifest_json: str, output_pdf: str) -> None:
    reader = PdfReader(input_pdf)
    writer = PdfWriter()
    writer.append(reader)

    specs = json.loads(Path(manifest_json).read_text(encoding="utf-8"))
    for spec in specs:
        add_widget(writer, spec)

    with open(output_pdf, "wb") as out_file:
        writer.write(out_file)
    print(f"Injected {len(specs)} interactive AcroForm widgets into {output_pdf}")


if __name__ == "__main__":
    if len(sys.argv) != 4:
        print("Usage: python reconstruct_acroform.py input.pdf fields_manifest.json output.pdf")
        sys.exit(1)
    main(sys.argv[1], sys.argv[2], sys.argv[3])

Notice /F 4 on the annotation dictionary: that is the Annotation Flags entry (ISO 32000-1 §12.5.3, bit 3 = Print), which is distinct from /Ff (Field Flags, §12.7.3.1). If you omit /F 4, a user can fill out the reconstructed PDF on screen, hit Ctrl+P, and get a blank printout because the viewer skips non-printable annotations during rasterization.

5. Detecting Candidate Lines and Anchor Labels Before Placing Widgets

When automating this across dozens of existing Word-exported templates, manually measuring [llx, lly, urx, ury] coordinates in points is tedious. A practical pipeline combines two passes:

Text Anchor Pass: Locate label tokens ("Date of Birth:", "Signature:", "EIN:", "Phone:") and their baseline coordinates across pages. If you are auditing a large multi-page agreement first to locate every clause or field prompt, you can search a PDF for a word across all pages to find exact page numbers and context occurrences before placing fields.
Vector / Underscore Pass:
- Inspect page content streams for horizontal stroke segments (x1 y m x2 y l S where |y2 - y1| < 0.5 and x2 - x1 > 30), or
- Match runs of 4+ consecutive underscores (_{4,}) or Unicode box characters (☐, □, ☑) in extracted text spans.

When you only need to turn a flattened export into an interactive document without writing custom pypdf coordinate scripts, you can convert Word to a fillable PDF or convert a PDF to a fillable form online by placing text fields, checkboxes, dates, and signature boxes visually on the canvas and exporting a clean PDF. And if someone sends you an already-exported static PDF that just needs quick inputs added and filled immediately, you can make a PDF fillable free directly in the browser (see also the interactive form converter workspace).

6. Checklist for Production-Safe Fillable PDFs

Whether you generate AcroForm fields in Python, LibreOffice Writer (which does export Content Controls as /Widget annotations when "Create PDF form" is enabled), or a browser PDF editor, verify these four details before shipping a template to end users or an automated filling pipeline:

Unique /T Field Names: Never reuse the same /T name for two distinct inputs unless you explicitly want synchronized duplicate fields (in AcroForm, widgets sharing the same /T inherit the same /V value automatically).
/F 4 Print Flag Set: Confirm bit 3 of /F is enabled on every /Widget annotation so printed and flattened copies retain user input.
Explicit /DA Font Resource: Always reference a standard 14 PDF font (/Helv, /Cour, /TiRo, /ZaDb) in /DA and declare it in /AcroForm/DR/Font so viewers without system font substitution do not crash when generating appearance streams.
Test Long Unicode Strings & Flattening: Fill the reconstructed fields with non-ASCII characters (diacritics, typographic quotes) and test rendering in Chrome PDFium, Mozilla PDF.js, and macOS Preview before locking the template.

Disclosure: I am the solo developer of JustFill.

AI disclosure: AI coding agents drafted and revised this article and verified the code examples above.

Fill Existing PDF Forms from n8n Without Rebuilding the Template

Maciej S. — Sat, 05 Sep 2026 16:57:20 +0000

An earlier version of this n8n workflow had a bad fallback: when it couldn't find an exact PDF field name, it tried a partial match. For example, an input called total could match a field called subtotal if there was no exact match.

The PDF would still be generated. The number would just be in the wrong box.

That fallback is gone in the current version. Below is the corrected workflow, a three-field PDF you can test it with, and what the latest test actually covered. I build JustFill, the PDF service used here.

Where the mapping went wrong

The old mapping node used find() with a substring fallback. It also stripped everything outside a-z and 0-9 when comparing names, which lost non-ASCII letters.

The replacement keeps Unicode letters and requires an exact match after normalization. This is the matching part of the Code node, not the complete node:

const norm = s => String(s ?? '')
  .normalize('NFC')
  .toLowerCase()
  .replace(/[^\p{L}\p{M}\p{N}]+/gu, '');

const nk = norm(k);
const matches = ws.fields.filter(f => norm(f.name) === nk);

So Company Name and company_name match; total and subtotal don't. If normalization gives two PDF fields the same name, the workflow rejects the ambiguity rather than choosing the first one.

The rest of the node rejects unknown input keys, two keys targeting one field, arrays, and nested objects. null writes a blank value. A PDF field left out of the input is optional; this code doesn't decide which fields your business process requires.

This still depends on the template being right. A correctly named field in the wrong place will produce a correctly matched value in the wrong place. Review the boxes once for each PDF version and save that layout before using it for recurring documents.

Try it with a supplier-intake PDF

Download the current workflow JSON from GitHub and use Workflows → Import from File in n8n. The catalog update was submitted for review on September 5, 2026. While the n8n listing is temporarily unavailable, use the repository file for this example.

The workflow fills the PDF you upload. It doesn't rebuild the document from HTML. It uses HTTP Request and Code nodes, so you don't need to install a community node or configure an LLM key.

Form Trigger (PDF + JSON)
  → request a one-time upload URL
  → POST the PDF binary
  → open_pdf
  → map field names
  → fill_pdf
  → redirect to the download URL

Create a JustFill key under Account → API keys and put it in the Config node for the test. That node stores the key in the workflow definition: don't share an export with the key inside it. For production, move it to an n8n credential or environment variable. The requests go to https://justfill.app/api/mcp as JSON-RPC over HTTP; the imported nodes already build the request bodies.

Open the form trigger's test URL, upload the sample supplier-intake PDF, and paste:

{
  "company_name": "Northwind LLC",
  "vendor_reference": "V-1042",
  "remittance_email": "ap@northwind.example"
}

This sample has three named AcroForm fields, so it doesn't need a separate template-preparation step. All values are synthetic. In the output, check the company, reference, and email boxes individually, then try adding unknown_field to the JSON. That second run should stop before filling.

Historical watermarked example showing the three field positions, not the clean output from the September 5 test.

What has actually been tested

The September 5, 2026 check ran the workflow's actual mapping code against production MCP upload, open, and fill responses. All three values appeared in the expected boxes in a clean PDF, which was also checked visually. An extra unknown key was rejected before filling. The temporary workspace and credential were removed afterward.

That was an HTTP-plus-Code-node test, not a new run inside the n8n engine. The cover image is from the earlier full workflow run on n8n 2.28.6, on July 20; it is not evidence of the September strict-mapping update.

You can run the mapping regression tests without n8n or an API key. From a checkout of the public justfill-mcp repository:

node --test examples/n8n/test-deterministic-mapping.mjs

The three-field test doesn't establish that a dense, multipage form will be laid out correctly. Test your actual PDF with synthetic values, including long text and any checkboxes, before connecting customer data.

Connecting your own data

For a recurring supplier form, replace the Form Trigger with your procurement webhook and construct just the three fields the PDF needs. Don't feed the mapper a whole supplier record: extra keys will now fail the run deliberately.

Replace the final redirect with your delivery step. Check output_mode before sending anything: it can be clean or watermarked. The download link is temporary, so if you need an archive, fetch the PDF and store it in your own destination.

The n8n setup guide collects the import files and template instructions. If your data is already a spreadsheet and you don't need n8n around it, the five-row Excel/CSV browser sample is a shorter way to check whether your PDF works.

Disclosure: I am the solo developer of JustFill.

AI disclosure: AI coding agents drafted and revised this article and ran the code checks described above.

DEV Community: Maciej S.

Automating State DMV Title & Dealer Packets (TX 130-U, CA REG 227/343, FL HSMV 82040, MO Form 108) from Spreadsheets & JSON

1. Inside State DMV PDFs: Why Standard AcroForm Scripts Break

Pitfall A: Empty-Password Owner Encryption & Permission Bitmasks (TX 130-U, OH BMV 3774)

Pitfall B: Per-Digit Split Widgets and Inconsistent Hierarchy (CA REG 227)

Pitfall C: Zero-Field Flattened Vector PDFs (OH BMV 3774, NY DTF-802 Sections)

2. State-by-State DMV Dealer & Fleet Packet Comparison

3. Inspecting Any State DMV PDF (inspect_dmv_pdf.py)

4. Unified Deal Log CSV & Mapping Schema (Direct, Sliced, and Coordinate Overlay)

5. Production Python Batch Filler for State DMV Packets (batch_fill_dmv_packets.py)

6. Automating DMV Dealer Batches from Excel/CSV or MCP Without Custom Coordinate Maps

7. Pre-Flight Checklist for Multi-State DMV Title Batches

How to Batch-Fill USCIS Immigration Packets (G-28, I-129, I-140, I-485, I-765) from CSV/JSON Without Adobe Acrobat or XFA Desync

1. Structural Anatomy of a 6-Form USCIS Filing Packet

2. Why One Canonical JSON Record Can't Naive-Match Across USCIS Forms

3. Python Pipeline: Inspecting & Batch-Filling a Multi-Form USCIS Packet

4. Handling USCIS LiveCycle Input Masks & Comb Fields (SSN, A-Number, I-94)

5. Browser & Spreadsheet Workflows for Legal Teams and HR Ops

Why USCIS & California Court PDFs (I-765, I-485, I-130, FL-150) Open Blank After Saving in macOS Preview — And How Hybrid XFA Works

1. Inside /Root -> /AcroForm: How Hybrid XFA PDFs Store Data Twice

2. Why macOS Preview Saves Open Blank in Windows Adobe Acrobat

3. Recovering "Blank" Preview PDFs & Stripping /XFA + /Perms in Python

4. Audited USCIS & California Court Forms & Browser Workflows

How to Mail Merge from Excel (.xlsx / CSV) into Official IRS & ACA PDFs (1095-C, W-9, Form 2848, SS-4) Without Adobe Acrobat

1. Why Official IRS PDFs Break Naive Mail-Merge Scripts

Pitfall A: Hierarchical Subform Paths and Positional /T Keys

Pitfall B: Hybrid /XFA Streams Overriding /AcroForm Values

Pitfall C: Checkbox /AS Appearance States (/1 vs. /Yes)

2. Inspecting IRS AcroForm Schemas (1095-C, 2848, SS-4, 843)

3. Structuring the CSV / Excel Input (aca_1095c_batch.csv)

4. Deterministic Python Batch Mail-Merge Script (csv / .xlsx → IRS PDFs)

Why del widget[NameObject("/AP")] Matters for Text Inputs

5. Browser-Based Mail Merge When You Don't Want to Maintain Field Maps

6. Pre-Flight Validation Checklist Before Generating 100+ Tax Forms

Why Exporting Word (.docx) to PDF Strips Form Fields (And How AcroForm Widget Reconstruction Works)

1. What Word Stores in .docx vs. What Lands in the PDF Stream

2. Anatomy of a Real Fillable PDF (/AcroForm + /Widget Annotations)

Key Dictionary Keys Engineers Need to Know

3. Coordinate Space Mismatch: DOM/Word Top-Left vs. PDF Bottom-Left

4. Reconstructing AcroForm Widgets in Python (pypdf)

5. Detecting Candidate Lines and Anchor Labels Before Placing Widgets

6. Checklist for Production-Safe Fillable PDFs

Fill Existing PDF Forms from n8n Without Rebuilding the Template

Where the mapping went wrong

Try it with a supplier-intake PDF

What has actually been tested

Connecting your own data

Pitfall A: Empty-Password Owner Encryption & Permission Bitmasks (`TX 130-U`, `OH BMV 3774`)

Pitfall B: Per-Digit Split Widgets and Inconsistent Hierarchy (`CA REG 227`)

Pitfall C: Zero-Field Flattened Vector PDFs (`OH BMV 3774`, `NY DTF-802` Sections)

3. Inspecting Any State DMV PDF (`inspect_dmv_pdf.py`)

5. Production Python Batch Filler for State DMV Packets (`batch_fill_dmv_packets.py`)

4. Handling USCIS LiveCycle Input Masks & Comb Fields (`SSN`, `A-Number`, `I-94`)

1. Inside `/Root -> /AcroForm`: How Hybrid XFA PDFs Store Data Twice

3. Recovering "Blank" Preview PDFs & Stripping `/XFA` + `/Perms` in Python

Pitfall A: Hierarchical Subform Paths and Positional `/T` Keys

Pitfall B: Hybrid `/XFA` Streams Overriding `/AcroForm` Values

Pitfall C: Checkbox `/AS` Appearance States (`/1` vs. `/Yes`)

2. Inspecting IRS AcroForm Schemas (`1095-C`, `2848`, `SS-4`, `843`)

3. Structuring the CSV / Excel Input (`aca_1095c_batch.csv`)

4. Deterministic Python Batch Mail-Merge Script (`csv` / `.xlsx` → IRS PDFs)

Why `del widget[NameObject("/AP")]` Matters for Text Inputs

1. What Word Stores in `.docx` vs. What Lands in the PDF Stream

2. Anatomy of a Real Fillable PDF (`/AcroForm` + `/Widget` Annotations)

4. Reconstructing AcroForm Widgets in Python (`pypdf`)