DEV Community: Lucien Chemaly

Top DocuSign API alternatives for developers in 2026

Lucien Chemaly — Fri, 18 Sep 2026 13:35:33 +0000

DocuSign retired basic user password authentication on September 30, 2024, ending support for the X-DocuSign-Authentication header that integrations had relied on since the early days of the eSign REST API. Any team still sending that header had to rebuild its auth layer on OAuth 2.0, where DocuSign supports three grant type families (Authorization Code, split into confidential and public variants, plus JWT and Implicit).

Most of those migrations shipped under deadline pressure, so the quickest path usually won and teams re-authenticated against DocuSign without weighing anything else. That forced work is now behind you, and nothing is forcing the next decision, which makes this a better moment to ask whether DocuSign still fits your SaaS application or whether another e-signature API serves it better.

This guide applies a consistent technical framework to six alternatives, evaluating each against five criteria (authentication model, embedded signing implementation, SDK language coverage, webhook event reliability, and compliance footprint) to give you a decision matrix you can act on.

Five technical criteria that drive the right choice

These five dimensions determine whether an API works in production, not just in a proof of concept. Each one maps to a real constraint you'll hit during integration.

OAuth2 grant type support. Most e-signature APIs support Authorization Code Grant for user-delegated flows and client_credentials for server-to-server automation. Embedded SaaS workflows typically run server-side, without a human in the auth loop at signing time. An API that requires Authorization Code Grant for every token request adds friction to automated pipelines.

Embedded signing model. The divide between iFrame embedding and redirect-based signing determines whether your signers ever leave your application. Redirect-based flows push users to a third-party domain, then return them via a callback URL. iFrame embedding keeps the signing UI inside your product's chrome. For SaaS teams building a white-labeled experience, iFrame is the stronger choice, but it requires the API to generate a signed session URL with correct CORS headers and sandbox attribute permissions.

SDK language coverage. An API without an SDK in your stack adds overhead, because you build and maintain HTTP clients, handle retry logic, and parse response schemas manually. SDK coverage signals how seriously a vendor treats developer experience at the integration layer.

Webhook event schema and reliability. Envelope status changes (signed, declined, voided) need to reach your application reliably and in a verifiable format. Webhook payloads vary across providers in schema structure, authentication method (HMAC-signed vs. unsigned), and retry behavior on delivery failure. A provider that signs payloads with HMAC and retries on failure is safer to build against than one that delivers once with no retry guarantee.

Compliance footprint. Your legal and security teams will flag this regardless. ESIGN and UETA cover US enforceability. GDPR applies whenever signers are EU residents. HIPAA and FDA 21 CFR Part 11 are hard requirements in healthcare and life sciences. Identify the standards your contracts and signers require before you run your first sandbox test.

Embedded signing alternatives

Foxit eSign

Foxit eSign uses the OAuth2 client_credentials grant, which works well for server-to-server SaaS workflows. You POST your client_id and client_secret to the regional OAuth2 endpoint to exchange credentials for a Bearer token. Foxit routes requests to regional infrastructure, with na1.foxitesign.foxit.com for US-hosted data and eu1.foxitesign.foxit.com for EU. Every subsequent API call carries that token in the Authorization: Bearer header.

The iFrame embedding model uses two parameters on the Create Envelope call. Setting createEmbeddedSigningSession to true suppresses email delivery and generates a session token. Setting createEmbeddedSigningSessionForAllParties to true generates individual signed URLs for each recipient. The resulting URL takes the form https://HOST_NAME/embedded/embeddedsign?eetid={URL-ENCODED-TOKEN}, which you drop into an <iframe> tag inside your application. After a recipient signs or declines, Foxit eSign redirects to the return URL you specified in the Create Envelope request, appending folderId and an event parameter (signing_success or signing_declined), so your application can act on the outcome without polling.

Published API sample code covers cURL, PHP, C#, and Java. Webhook channels fire on envelope status changes including EXECUTED, and you can configure a webhookSecret so your endpoint can validate HMAC-signed delivery payloads. The compliance footprint covers ESIGN, UETA, GDPR, HIPAA, CCPA, and FDA 21 CFR Part 11, making Foxit eSign viable for healthcare and life-sciences workflows that require Part 11 audit trails and long-term record validation.

A free developer account is available at app.developer-api.foxit.com/sign-up with no credit card required. Full API reference lives at docs.developer-api.foxit.com. For current plan pricing, see the Foxit eSign API credits page.

Dropbox Sign

Dropbox Sign (formerly HelloSign) supports OAuth2 Authorization Code Grant alongside API key authentication. For embedded signing, the API generates a sign_url via an embedded signing request. You render that URL inside an iFrame using Dropbox Sign's JavaScript client library, which manages the signer handshake and posts completion events back to the parent page.

Official SDKs cover Node, Python, Ruby, Java, PHP, and .NET. Webhooks deliver signature request events validated via a callback hash. The compliance footprint includes ESIGN, UETA, GDPR, and HIPAA, though HIPAA support requires an annual Standard or Premium plan plus a signed Business Associate Agreement rather than being available on every tier. A free Test mode plan lets you build and exercise the full API before committing, with paid tiers starting once you send live signature requests. For current plan details, see the Dropbox Sign API pricing page.

Dropbox Sign's embedded model requires loading the JavaScript SDK in the parent page, adding a client-side dependency. Teams that want a purely server-rendered iFrame approach without a JS dependency will find that coupling inconvenient, particularly in server-side-rendered stacks where loading a third-party client script creates CSP friction.

SignNow

SignNow, an airSlate product, supports the OAuth2 password, refresh_token, and authorization_code grants, where the authorization code grant covers applications acting on behalf of an individual SignNow user rather than the signing flow itself. Embedded signing runs on a bearer token or API key, so the signer never touches OAuth. You create an embedded invite via the API, generate a link for that invite, then render it in an iFrame inside your application.

SignNow publishes SDKs for PHP, .NET, Java, Python, and Node.js, with an Android SDK added more recently. Compliance certifications cover ESIGN, UETA, HIPAA, GDPR, and SOC 2 Type II, alongside 21 CFR Part 11, PCI DSS, eIDAS, and CCPA. For developer plans, see the SignNow API pricing page.

The webhook layer delivers user, document, and document_group events, and you can have them HMAC-signed by supplying your own secret when you create the subscription, which arrives as an X-SignNow-Signature header holding a base64 HMAC-SHA256 digest. Signing is opt-in rather than the default, so an integration that skips the secret receives unauthenticated callbacks. Recipient identity verification is configured per recipient on the invite and offers a password, an SMS code, or a phone-call code.

Document automation and open-source alternatives

DocuSeal

DocuSeal is an open-source e-signature platform designed for self-hosting, making it the primary option for teams with strict data-residency requirements. Documents stay inside your infrastructure rather than transiting a third-party cloud. The API authenticates with an API key sent in a custom X-Auth-Token header rather than an Authorization: Bearer header, which is the one place a migration script written against the other providers in this guide needs a different code path. The embedded signing UI ships as a <docuseal-form> JavaScript web component, with official React, Vue, and Angular wrappers you mount in your front end.

The open-source repository is available on GitHub under AGPLv3 with additional attribution terms, and a managed cloud version is also offered. First-party SDKs cover Ruby, JavaScript and TypeScript, Python, PHP, Java, C# and .NET, and Go, so the self-hosted path is not limited to the two languages the project started with. Because you control the infrastructure, you control data location, which addresses GDPR data-residency obligations that cloud-only providers cannot satisfy without a Data Processing Agreement and region-locked storage commitments. For cloud pricing and self-hosting configuration details, see the DocuSeal pricing page.

Read that compliance list with the deployment model in mind. The SOC 2 Type II and ISO 27001 certifications cover DocuSeal's own managed cloud, so when you self-host, the audit evidence for your environment becomes your responsibility rather than the vendor's. Running self-hosted signing infrastructure also means your team owns uptime, secret key management, and upgrade cycles, and that operational burden is the direct trade-off for the data control DocuSeal provides.

BoldSign

BoldSign targets SaaS developers embedding signing into customer-facing products. Authentication supports OAuth2 (client_credentials and Authorization Code Grant) and API key. The embedded signing flow generates a signed URL you render in an iFrame, with no client-side JS SDK dependency required.

Official SDKs are published for .NET, Java, Python, Node.js, and PHP. Webhooks fire on document status events and support HMAC-signed payload validation. The compliance footprint covers ESIGN, UETA, HIPAA, and GDPR, though HIPAA support sits on the Business tier rather than the entry plans. A genuinely free plan is available rather than a time-boxed trial. For full plan details, see the BoldSign pricing page.

BoldSign's API documentation covers the full envelope lifecycle with code samples across its published SDK languages, and the free plan's limits make it a workable tier for integration testing without a time-boxed trial window.

PandaDoc

PandaDoc covers a wider scope than pure e-signature. The platform addresses full document automation, including template management, proposal generation, and CPQ (configure, price, quote) document creation, with e-signature as one output in that pipeline. The API supports OAuth2 Authorization Code Grant and API key authentication. Embedded signing runs on a session URL, which PandaDoc now recommends rendering through its pandadoc-signing client library rather than wiring the iFrame by hand.

Official client SDKs are published for Python, Node, Java, and PHP, with Ruby and .NET available only as community-maintained wrappers. Webhooks fire on document events with callback validation. The compliance footprint includes ESIGN, UETA, HIPAA, GDPR, and SOC 2 Type 2, though transmitting protected health information requires signing a Business Associate Agreement with PandaDoc rather than relying on the platform default. Sandbox API calls are free of charge for development, though the sandbox key itself is only available on the Business or Enterprise plan, and a production key requires Enterprise plus manual activation by PandaDoc, so factor both gates into any timeline. For current rates, see the PandaDoc pricing page.

Teams that need document generation, CRM-driven template population, and signing in a single workflow will find the broader platform scope worth the integration surface area. Teams evaluating PandaDoc for e-signature alone should factor in that breadth before committing, since it drives both API complexity and plan cost.

Comparison at a glance

Tool	Auth Model	Embedded Signing	SDK Languages	Compliance	Free API Tier
Foxit eSign	OAuth2 `client_credentials`	iFrame via `createEmbeddedSigningSession`	cURL, PHP, C#, Java	ESIGN, UETA, GDPR, HIPAA, CCPA, FDA 21 CFR Part 11	Yes (no credit card; 30-day trial in test mode)
Dropbox Sign	OAuth2 + API key	iFrame + JS client library	Node, Python, Ruby, Java, PHP, .NET	ESIGN, UETA, GDPR, HIPAA (Standard/Premium plan + BAA)	Yes (free Test mode)
SignNow	OAuth2 (password, auth code, refresh) + API key	iFrame via embedded invite	PHP, .NET, Java, Python, Node.js, Android	ESIGN, UETA, HIPAA, GDPR, SOC 2, 21 CFR Part 11, eIDAS	Yes (free Dev Mode test tier)
DocuSeal	API key (`X-Auth-Token`)	iFrame (web component)	Ruby, JS/TS, Python, PHP, Java, C#/.NET, Go	ESIGN, UETA, eIDAS, GDPR, HIPAA, 21 CFR Part 11, SOC 2, ISO 27001	Yes (open source / limited cloud)
BoldSign	OAuth2 + API key	iFrame	.NET, Java, Python, Node.js, PHP	ESIGN, UETA, HIPAA, GDPR	Yes (free plan)
PandaDoc	OAuth2 Auth Code + API key	iFrame via `pandadoc-signing`	Python, Node, Java, PHP	ESIGN, UETA, HIPAA (BAA), GDPR, SOC 2	Sandbox calls free (Business/Enterprise plan); production requires Enterprise

Verify all cells against each vendor's current documentation before making a selection, as SDK and compliance details change with platform updates.

How to migrate from DocuSign to a new API

The five steps below apply regardless of which alternative you choose. Each step is designed to be verified in isolation so you catch provider-specific behavioral differences before touching production.

flowchart LR
    A[Generate<br/>OAuth2 Credentials] --> B[Test Token<br/>Exchange in Sandbox]
    B --> C[Repoint<br/>Authorization<br/>Header]
    C --> D[Remap Webhook<br/>Event Payloads]
    D --> E[Swap SDK<br/>Dependency]
    E --> F[Run Test Suite<br/>Against New Sandbox]

Step 1. Generate new OAuth2 credentials.

Every provider in this guide uses a client_id and client_secret as the starting point. Create a sandbox account, retrieve your credentials from the developer portal, and export them as environment variables so they never end up in your shell history or a committed file. Then use Postman or a direct cURL call to confirm you can exchange them for a Bearer token. For a client_credentials flow such as Foxit eSign, the request looks like this:

curl --location "https://$REGIONAL_ENDPOINT/api/oauth2/access_token" --header 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'grant_type=client_credentials' --data-urlencode "client_id=$CLIENT_ID" --data-urlencode "client_secret=$CLIENT_SECRET" --data-urlencode 'scope=read-write'

In this command, you post your credentials to the provider's token endpoint as a form-encoded body rather than JSON, which matters because Foxit eSign rejects a JSON body on this endpoint with HTTP 415. The grant_type and scope values tell the provider you want a server-to-server token with read and write access. Read the credentials from $CLIENT_ID and $CLIENT_SECRET in your environment so the values stay out of the command itself.

A successful exchange returns the token alongside its type and remaining lifetime:

{"access_token":"REDACTED","token_type":"bearer","expires_in":23480263,"instance_url":"https://na1.foxitesign.foxit.com/"}

The instance_url confirms which regional host issued the token, and every call you make afterwards sends Authorization: Bearer <access_token> against that same host.

For Authorization Code flows (Dropbox Sign, SignNow, PandaDoc), follow that provider's OAuth2 redirect sequence to obtain your initial token. Confirm the token arrives before writing any application code.

Step 2. Repoint the Authorization header at your new provider.

Since the legacy header stopped working in 2024, your DocuSign integration already sends an OAuth 2.0 Bearer token:

Authorization: Bearer {DOCUSIGN_ACCESS_TOKEN}

Every provider in this guide uses that same header shape, so what changes is which service issued the token, not how you attach it:

Authorization: Bearer {ACCESS_TOKEN}

That makes the transport change small and the token-acquisition change the real work, which is why Step 1 comes first. If your codebase predates the retirement, grep for X-DocuSign-Authentication as well and delete any leftover credential-construction logic that still assembles the old JSON payload, since that code is dead and only obscures which auth path is live.

Step 3. Remap webhook event payloads.

DocuSign's Connect service uses its own envelope status event schema. Your new provider uses a different schema with different field names, status strings, and nesting. Map the fields your current handler consumes (envelope ID, signer email, completion timestamp, event type) to the new provider's equivalent fields. Build a translation layer that converts the new provider's payload into the shape your downstream code already expects. This approach keeps your business logic untouched and isolates the mapping delta to a single module you can test independently.

Step 4. Swap the SDK dependency.

Remove the DocuSign SDK from your package manager and install the equivalent SDK for your new provider. Compile-time errors and type mismatches surface immediately. Work through them method by method, keeping business logic (what you do with a completed envelope) separate from transport logic (how you call the API), so the two don't share state.

Step 5. Run your existing test suite against the new sandbox.

Your existing integration tests should pass against the new provider's sandbox before you touch production. Any test that fails points to a schema delta or a behavioral difference you need to handle explicitly. Fix the underlying mismatch rather than disabling the test.

The three variables that actually decide

Your embedded signing model (iFrame vs. async redirect), your required SDK language coverage, and your compliance obligations are the three variables that determine the right e-signature API for your stack.

DocuSeal is the right answer when data residency and self-hosted control are non-negotiable. PandaDoc fits teams that need document automation alongside signatures as part of a single pipeline. BoldSign and Foxit eSign both target embedded SaaS use cases, with BoldSign standing out for a free tier that sends real envelopes rather than test-only traffic, and Foxit eSign covering the regulated-industry compliance surface (including HIPAA and FDA 21 CFR Part 11) that healthcare and life-sciences teams require.

Read the free tiers carefully, because they are not equivalent. Dropbox Sign's Test mode and SignNow's Dev Mode give you an unlimited test environment but no live signatures, PandaDoc's sandbox is free while production is gated behind the Enterprise plan, and Foxit eSign's self-serve developer activation provisions a 30-day trial in test mode with watermarked envelopes before production access goes through Foxit. BoldSign's free plan is the outlier, allowing a small monthly volume of genuine envelopes. A tier that looks generous in a comparison table can still stop at the exact moment you want to ship.

If Foxit eSign's iFrame-embedded model and compliance depth fit your stack, the free developer account at app.developer-api.foxit.com/sign-up gives you API keys and a full sandbox environment with no credit card required.

Which of the five evaluation criteria is the hardest constraint in your current stack? Share in the comments.

How to extract invoice data from PDFs into structured JSON

Lucien Chemaly — Fri, 18 Sep 2026 13:35:22 +0000

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

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

Why invoice PDFs break generic parsers

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

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

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

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

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

Invoice fields to target before touching the API

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

A workable invoice schema covers three groups:

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

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

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

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

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

Prerequisites

You need the following before the first API call:

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

Scaffold the workspace in one shot:

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

Then download the sample invoice into that folder:

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

Foxit API authentication and setup

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

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

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

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

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

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

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

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

The four-step PDF to JSON invoice extraction workflow

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

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

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

import io
import json
import os
import time
import zipfile

import requests

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


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

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

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

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

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

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

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

How to map raw output to a clean invoice schema

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

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

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

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

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

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

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


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

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

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

import re

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


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

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

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

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

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

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

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

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

    return invoice

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

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

Before and after

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

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

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

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

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

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

Common mistakes

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

FAQ

What is invoice data extraction from PDF?

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

How do I extract line items from a PDF invoice?

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

Can an extraction API handle scanned PDF invoices?

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

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

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

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

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

What element types does the API classify?

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

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

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

Wrapping up

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

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

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

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

How to turn PDFs into structured data with a PDF data extraction API

Lucien Chemaly — Fri, 18 Sep 2026 13:35:11 +0000

The document renders fine in a PDF viewer. The moment your code tries to read it, you're looking at a flat string with no table structure, no reading order, and no way to tell which values belong to which labels.

PDFs dominate data-intensive workflows, including invoices, contracts, financial reports, and scanned intake forms. The format was designed for visual fidelity, not machine readability. Text extraction libraries can pull words off a page, but they discard the structure that makes those words useful, including which column a number belongs to, whether a line is a table header or a paragraph, and whether a field is a form input or surrounding prose.

This guide shows you how to solve that with a REST-based PDF data extraction API. You'll see the four-step request lifecycle, the practical difference between basic text extraction and AI-assisted structural extraction, and how to route the resulting JSON into a downstream system. Every request and response below comes from a live run against Foxit's PDF Services API, with examples in both shell and Python.

Why basic PDF parsing breaks down

PDFs don't have a single internal format. A word-processor export has a proper text layer. A scanned invoice is a bitmap with no text whatsoever. A multi-column research paper has text objects positioned on the page without semantic grouping. Form fields sit in a separate data structure from the body text around them.

Naive extraction libraries treat all of these the same way, walking the PDF content stream and concatenating text objects in order. The output is readable but structurally blind. A two-column table becomes a jumbled stream that interleaves values from the left and right columns. Reading order is lost. Headers are indistinguishable from body text. Form field labels merge with their values.

For simple use cases such as keyword search or full-text indexing, that's often acceptable. If you need to populate a database field from an invoice line item, compare figures across financial reports, or feed structured records into a retrieval augmented generation (RAG) pipeline, flat text output breaks the downstream system before it starts. Modern AI and business intelligence tools expect schema-consistent JSON, not raw strings.

How to choose the right extraction approach

Three broad approaches exist for getting structured data out of PDFs, covering rule-based, template-based, and AI-assisted structural extraction. Tools like Adobe PDF Extract API, Amazon Textract, Google Document AI, Nutrient, and Apryse all land somewhere on this spectrum.

Rule-based extraction uses regular expressions and positional heuristics, finding the number 10 pixels to the right of the label "Invoice Total" and returning it. This works well for identical, high-volume layouts from a single source (one vendor's purchase orders, for example) but breaks the moment a layout changes by even a few pixels.

Template-based extraction pre-defines field positions for known document types. It's more flexible than pure rules but still requires a template per document variant. Maintenance overhead climbs quickly when you're processing documents from dozens of suppliers.

AI-assisted structural extraction uses machine learning to classify content regions regardless of layout. It recognizes a block of cells as a table even when that table has merged headers, irregular spacing, or no visible grid lines. It handles documents with variable layouts without requiring per-template configuration, and it applies optical character recognition (OCR) to scanned documents that have no text layer at all.

For consistent, known layouts at high volume, rule-based or template-based approaches are viable and predictable. For mixed-layout documents, variable vendor formats, or content headed into AI or BI pipelines that expect typed JSON, AI-assisted structural extraction is the right default.

Prerequisites

Before running any of the code below, get the following in place.

Runtime : Python 3.8 or later
Package manager : pip, bundled with modern Python installs
Environment isolation : venv, part of the standard library
HTTP library : requests, installed with pip
CLI tool : cURL for the raw HTTP examples
Code editor : VS Code with the Python extension is a reasonable default, and PyCharm or Sublime Text work equally well
Foxit developer account : sign up at app.developer-api.foxit.com/sign-up for a client ID and client secret, with no credit card required

Scaffold the workspace in one shot:

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

The commands above create a project directory, build an isolated virtual environment inside it, activate that environment so installs stay local to the project, and add the one third-party library the Python examples need.

API access and authentication setup

Once you're logged in, copy the client ID and client secret from the default application in the developer portal. Every request passes both values as lowercase headers, and there is no separate token exchange step, so a request is authenticated as soon as those two headers are present.

The sign-up page the CTA points at. The panel on the right is where the client ID and client secret come from, and the free tier is enough to complete this whole walkthrough.

export FOXIT_CLIENT_ID="your-client-id"
export FOXIT_CLIENT_SECRET="your-client-secret"

Exporting the credentials as environment variables keeps them out of your source files and out of your shell history if you set them in a profile. Every example below reads them from the environment rather than hard-coding a literal.

The base URL for every call in this guide is https://na1.fusion.foxit.com/pdf-services/api, and it stays constant across upload, extraction, polling, and download. The interactive API reference documents each endpoint's request and response shape if you need more detail than this walkthrough covers.

Foxit also provides an on-premise PDF SDK for air-gapped or offline environments, though this guide covers the cloud REST API only.

Calling the PDF data extraction API endpoints

Every extraction job runs asynchronously and follows four steps, covering upload, job start, polling, and download. There is no synchronous variant, because layout analysis on a multi-page document takes longer than a typical request timeout allows.

The four calls in order. Each one returns exactly the identifier the next one needs.

Each call returns exactly what the next one needs. An upload produces a documentId, starting a job produces a taskId, and a finished job produces a resultDocumentId.

Step 1: Upload the document

Send the PDF as multipart form data, with the file attached under the field name file. Use this sample invoice if you'd rather not supply your own document. It carries a five-column line-item table, which exercises both row and column indexing later on.

The source document. Notice that "API Integration Consulting" wraps onto two lines inside its cell, which matters once you start comparing cell text.

curl -X POST "https://na1.fusion.foxit.com/pdf-services/api/documents/upload" -H "client_id: $FOXIT_CLIENT_ID" -H "client_secret: $FOXIT_CLIENT_SECRET" -F "file=@invoice_table_test.pdf"

The command above posts the PDF as multipart form data and returns a JSON body containing a documentId. Capture that value, because every later call in the flow depends on it.

Step 2: Start the extraction job

Foxit provides two extraction endpoints, and the right one depends on what your pipeline consumes.

Basic extraction (POST /pdf-services/api/documents/modify/pdf-extract) returns flat text, image, or page-level output. It requires an extractType parameter, and the accepted values are TEXT, IMAGE, and PAGE, in uppercase. Sending a lowercase value returns a VALIDATION_ERROR rather than falling back to a default. Use this endpoint when you want raw text or image assets and your own code handles the parsing.

Structural extraction (POST /pdf-services/api/documents/pdf-structural-extract) applies OCR, layout recognition, and classification to sort content into twelve element types, covering title, head, paragraph, table, image, headerFooter, form, hyperlink, footnote, sidebar, annotation, and formula. It preserves reading order, spatial position, and table cell grids, including for scanned documents with no existing text layer.

curl -X POST "https://na1.fusion.foxit.com/pdf-services/api/documents/pdf-structural-extract" -H "client_id: $FOXIT_CLIENT_ID" -H "client_secret: $FOXIT_CLIENT_SECRET" -H "Content-Type: application/json" -d '{"documentId": "YOUR_DOCUMENT_ID"}'

This request starts the analysis job and returns HTTP 202 with a taskId rather than a finished result. The 202 is the signal that work has been queued, so treat any expectation of inline output as a bug in your integration rather than a slow response.

Step 3: Poll for completion

Poll the task endpoint until the status reaches a terminal value. Status strings are uppercase, and the sequence runs PENDING, IN_PROGRESS, then either COMPLETED or FAILED.

curl -X GET "https://na1.fusion.foxit.com/pdf-services/api/tasks/YOUR_TASK_ID" -H "client_id: $FOXIT_CLIENT_ID" -H "client_secret: $FOXIT_CLIENT_SECRET"

The response carries taskId, status, progress, and, once the work finishes, resultDocumentId. A three-second interval between polls is a sensible default for single-page documents.

Step 4: Download the result

curl -X GET "https://na1.fusion.foxit.com/pdf-services/api/documents/YOUR_RESULT_DOC_ID/download" -H "client_id: $FOXIT_CLIENT_ID" -H "client_secret: $FOXIT_CLIENT_SECRET" -o result.zip

The download returns application/zip. Inside are two kinds of file, StructureInfo.json holding the extracted content, and one PNG per detected table region. Despite a filename like page_p0.pdf_0.png, that image is a crop of the table rather than a render of the whole page.

The whole sequence against the live API. Note the 202 on the extract call, the COMPLETED status before any download is attempted, and the archive listing exactly two files.

The PNG that shipped in the ZIP for the invoice above, at 437 by 84 pixels. It shows the detected table only, which is a useful way to confirm the API found the region you expected.

Here is the shape of the JSON, trimmed to one element of each kind:

{
  "analyzeResult": {
    "version": { "schema": "1.0.7", "software": "FoxitPDFAnalyzer", "model": "idp-analysis" },
    "pages": [
      { "pageNumber": 1, "size": { "width": 612, "height": 792, "unit": "point" }, "state": "success" }
    ],
    "elements": [
      {
        "type": "title",
        "id": "e1",
        "score": 0.99,
        "content": { "text": "INVOICE" },
        "region": { "page": 1, "boundingBox": [72, 60, 240, 60, 240, 96, 72, 96] }
      },
      {
        "type": "table",
        "id": "e7",
        "region": { "page": 1, "boundingBox": [48, 360, 812, 360, 812, 512, 48, 512] },
        "content": {
          "body": {
            "rowCount": 4,
            "columnCount": 5,
            "cells": [
              { "rowIndex": 0, "columnIndex": 1, "rowSpan": 1, "columnSpan": 1,
                "paragraph": { "content": { "text": "Description" } } },
              { "rowIndex": 1, "columnIndex": 1, "rowSpan": 1, "columnSpan": 1,
                "paragraph": { "content": { "text": "API Integration\r\nConsulting" } } }
            ]
          }
        }
      }
    ]
  }
}

Three details in that payload decide whether your parsing code works. Every element sits under analyzeResult, so there is no top-level elements key to index. Element text lives at content.text rather than on the element itself. And region.boundingBox is an eight-number polygon describing four corner pairs, not a four-number rectangle, so unpacking it into x, y, width, height raises an error.

The same file from the run above, abbreviated. The highlighted keys are the four that parsing code gets wrong most often, and the eight numbers under boundingBox are what a four-value unpack trips over.

Processing structured JSON output in your pipeline

Tables are the part most likely to surprise you. A table element exposes content.body with rowCount, columnCount, and a flat cells array, where each cell carries its own rowIndex and columnIndex. There is no two-dimensional rows array and no separate headers array, so you build the grid yourself from those indexes.

import json
import zipfile


def clean(text):
    """Normalize cell text.

    A label that wraps inside its cell arrives with a literal \\r\\n in the
    middle of the string, so .strip() leaves it untouched. Splitting and
    rejoining collapses any internal whitespace run into a single space.
    """
    return " ".join(text.split())


def table_to_records(table):
    body = table["content"]["body"]
    grid = [["" for _ in range(body["columnCount"])] for _ in range(body["rowCount"])]
    for cell in body["cells"]:
        text = cell.get("paragraph", {}).get("content", {}).get("text", "")
        grid[cell["rowIndex"]][cell["columnIndex"]] = clean(text)
    header, *rows = grid
    return [dict(zip(header, row)) for row in rows]


with zipfile.ZipFile("result.zip") as archive:
    with archive.open("StructureInfo.json") as handle:
        data = json.load(handle)

elements = data["analyzeResult"]["elements"]

tables = [el for el in elements if el["type"] == "table"]
paragraphs = [el for el in elements if el["type"] == "paragraph"]

for table in tables:
    for record in table_to_records(table):
        print(record)

In this code, you open the downloaded archive and read StructureInfo.json directly out of it without unzipping to disk, index into analyzeResult to reach the element list, then filter that list by type to separate tables from prose. For each table, table_to_records allocates an empty grid from the reported row and column counts, drops each cell into position using its own indexes, and finally zips the first row against the remaining rows to produce one dictionary per line item. Those dictionaries map directly onto database columns or a pandas DataFrame.

Running it against the sample invoice prints:

{'#': '1', 'Description': 'API Integration Consulting', 'Qty': '10', 'Unit Price': '$ 150.00', 'Line Total': '$1,500.00'}
{'#': '2', 'Description': 'Compliance Review', 'Qty': '5', 'Unit Price': '$ 200.00', 'Line Total': '$1,000.00'}
{'#': '', 'Description': '', 'Qty': '', 'Unit Price': 'Subtotal:', 'Line Total': '$2,500.00'}

Notice that Description reads "API Integration Consulting" on one line, because clean collapsed the wrapped \r\n that the source cell contained. Notice too that the subtotal row arrives as a normal row with empty leading cells, so a pipeline writing straight to a database should skip rows whose key columns are blank rather than assuming every row is a line item.

Filtering by type is the pattern that generalizes. Paragraph and title elements drop into a chunking function for a RAG pipeline, already separated by semantic type. Table records go to a warehouse or a BI dashboard. Each element also carries a score, and a low value is worth a manual check before you trust the result downstream.

Common mistakes and troubleshooting

Most failures in this flow come from a small set of predictable causes.

Reading data["elements"] : there is no top-level elements key. The correct path is data["analyzeResult"]["elements"], and skipping that level raises a KeyError.
Unpacking boundingBox as four numbers : it is an eight-number polygon of four corner pairs, so code expecting x, y, width, height raises a ValueError. There is no bbox key.
Reading table["rows"] or table["headers"] : neither key exists. Build the grid from rowIndex and columnIndex as shown above.
Reading label and value from a form element : form elements do not carry those fields. Read the element's text and position instead.
Comparing status in the wrong case : status values are uppercase, so a test against "completed" never matches.
Calling .strip() on cell text : a wrapped label contains \r\n in the middle of the string, where strip has no effect. Normalize with " ".join(text.split()).
Sizing a loop from info.basicInfo.elementCounts : that summary and the elements array can disagree. On the sample invoice it reported 25 paragraphs while elements held 5, so count the array you are about to iterate rather than trusting the metadata.
Omitting extractType on basic extraction : modify/pdf-extract rejects the request with VALIDATION_ERROR until you pass TEXT, IMAGE, or PAGE.
Downloading before the task reports COMPLETED : polling once and assuming success yields a resultDocumentId that does not exist yet.

What this workflow handles end to end

The four-step PDF data extraction API workflow handles everything from a single invoice to thousands of mixed-layout reports processed overnight. Use basic extraction when you want raw text or images, and structural extraction when your pipeline needs typed JSON with preserved tables, reading order, and element classification. Processing a batch means looping the same sequence per file and tracking each taskId independently, so one slow document does not stall the rest.

On the compliance side, Foxit encrypts API traffic with TLS 1.2 or higher and protects documents at rest with AES-256, on SOC 2 Type II certified infrastructure. Support for HIPAA (through a business associate agreement), GDPR, and CCPA is documented on Foxit's API security and compliance page, which is worth reading before you route regulated documents through any hosted pipeline.

Create a free account at app.developer-api.foxit.com/sign-up and run the upload, extract, poll, and download sequence against one of your own documents. What extraction problems have you hit in your own pipelines? Drop them in the comments.

A developer's guide to eSignature API integration

Lucien Chemaly — Fri, 18 Sep 2026 13:34:39 +0000

Most signing integrations follow the same shortcut, redirecting the user to a hosted signing page, then polling an endpoint until the status flips to "completed." That works well enough for simple workflows, but breaks down when enterprise customers expect to stay inside your product, when a healthcare deployment requires a HIPAA-compliant audit trail your team actually controls, and when eIDAS 2.0 compliance across the EU means you can't treat conformance as an afterthought.

This guide covers the full integration path for a production-grade eSignature API, from OAuth2 token acquisition and PDF field placement to embedded signing sessions and webhook-driven completion handling. You'll come away with working patterns for every layer of the stack, all verified against the live Foxit eSign API.

Prerequisites

Everything here runs against real endpoints, so set up a workspace before the first request:

Python 3.8+ with pip, plus a virtual environment so the dependencies stay isolated.
The requests library for the API calls and Flask for the webhook receiver.
A free Foxit eSign developer account, created with no credit card. Activate the API tab in your account settings to get a client_id and client_secret.
A tagged sample PDF, so you don't have to author one. This guide uses agreement-signable.pdf, which already carries Text Tags for a single signer.
A code editor. VS Code with the Python extension is a good default; any editor works.

Scaffold the workspace in one shot, then store your credentials as environment variables so they never land in source control:

mkdir foxit-esign && cd foxit-esign
python3 -m venv .venv && source .venv/bin/activate
pip install requests flask
export ESIGN_CLIENT_ID="your_client_id"
export ESIGN_CLIENT_SECRET="your_client_secret"

API concepts and compliance baseline

The Foxit eSign API organizes signing workflows around folders. A folder holds one or more documents, a list of parties (signers, approvers, carbon-copy recipients), and the metadata that governs how those parties interact with those documents.

Fields inside a document (signature boxes, text inputs, date stamps) are each assigned to a specific party. You can define that assignment in two ways, either by embedding Text Tags directly in the PDF to bake field definitions into the file itself, or by specifying field ownership in the API call. When both the API request and the PDF tags supply recipient or party information, the API call values take precedence.

Signing order is controlled by three workflow modes, all driven by the signInSequence parameter:

Sequential: parties sign one after another in a defined order, and the next signer receives access only when the previous one completes.
Parallel: all parties receive signing access simultaneously (signInSequence set to false).
Hybrid: a mix of sequential stages, each of which may contain multiple parallel signers.

Before you write a line of code, establish your compliance scope. HIPAA, eIDAS Advanced Electronic Signatures (AES) and Qualified Electronic Signatures (QES), ESIGN, and UETA are supported out of the box. For healthcare deployments, confirm HIPAA configurations with your account team before go-live. For EU deployments, choose the eu1 regional endpoint to keep data residency inside the EU and satisfy eIDAS 2.0 requirements. Make these architecture decisions at the start, because waiting until a customer's legal team raises them costs you a re-architecture.

Authentication

Foxit eSign uses the OAuth 2.0 client-credentials grant. You exchange a client_id and client_secret, available under the API tab in your Foxit eSign account settings, for a short-lived Bearer token that authorizes all subsequent calls.

Get these two things right before you hit the endpoint:

The request body must be form-encoded (application/x-www-form-urlencoded). Sending a JSON body returns HTTP 415. Use requests.post(url, data={...}), not json={...}.
Choose your regional host at token time: na1.foxitesign.foxit.com for US deployments, eu1.foxitesign.foxit.com for EU. Both return the same error shape for bad credentials.

import os
import requests

# Regional endpoint (swap na1 for eu1 for EU data residency)
TOKEN_URL = "https://na1.foxitesign.foxit.com/api/oauth2/access_token"

# Body must be form-encoded. A JSON body returns HTTP 415.
response = requests.post(
    TOKEN_URL,
    data={
        "grant_type": "client_credentials",
        "client_id": os.environ["ESIGN_CLIENT_ID"],
        "client_secret": os.environ["ESIGN_CLIENT_SECRET"],
        "scope": "read-write",
    },
)

token_data = response.json()

# Response fields: access_token, token_type, expires_in, instance_url
access_token = token_data["access_token"]
instance_url = token_data["instance_url"].rstrip("/")  # base URL for all calls

# Attach the Bearer token to every downstream API request
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json",
}

The code above reads your credentials from the environment, posts them as a form-encoded body to the regional token endpoint, and unpacks the response. The instance_url it returns is already a full URL, so use it directly as the base for every downstream call rather than prepending a scheme yourself. Cache the token and schedule a refresh before expires_in seconds elapse, because re-acquiring on every request adds unnecessary overhead. For account activation steps, the Foxit eSign developer quickstart covers those without repetition here.

Preparing and sending a document

Create the document

You can supply a PDF two ways. Pass a publicly accessible HTTPS URL in fileUrls and Foxit fetches the file, or send the bytes inline by setting inputType to "base64" and passing the encoded string in a base64FileString array when the PDF lives behind authentication or hasn't been published externally.

Define recipients and field ownership

Define each signer as a party with a first name, last name, email address (emailId), a sequence number, and a permission such as FILL_FIELDS_AND_SIGN. Assign field ownership either via Text Tags embedded in the PDF or by specifying field coordinates in the API call. A Text Tag follows the syntax ${fieldtype:party_number:required:field_name:width}, so a required signature for the first party looks like ${signfield:1:y:____}, where y marks the field required, the party number maps to a signer's sequence, and width is expressed as underscores. If the API call and the PDF tags both specify party information, the API call wins.

Send modes

Two request parameters control how a document goes out. Choose based on whether you need a human review step or an in-app signing experience.

Draft creates the document but holds it for review. Set sendNow to false and no invitation email goes out, which suits flows where a user confirms the recipient list before the envelope is dispatched.

{
  "folderName": "Service Agreement - Acme Corp",
  "sendNow": false,
  "fileUrls": ["https://your-storage.example.com/agreement.pdf"],
  "fileNames": ["agreement.pdf"],
  "parties": [
    {
      "firstName": "Jane",
      "lastName": "Smith",
      "emailId": "jane@acme.com",
      "permission": "FILL_FIELDS_AND_SIGN",
      "sequence": 1
    }
  ]
}

Direct send dispatches immediately with no intermediate review step. Flip sendNow to true and Foxit emails the signers right away.

{
  "folderName": "NDA - Standard",
  "sendNow": true,
  "fileUrls": ["https://your-storage.example.com/nda.pdf"],
  "fileNames": ["nda.pdf"],
  "parties": [
    {
      "firstName": "Alex",
      "lastName": "Rivera",
      "emailId": "alex@partner.com",
      "permission": "FILL_FIELDS_AND_SIGN",
      "sequence": 1
    }
  ]
}

Embedded signing adds createEmbeddedSigningSession and a list of embeddedSignersEmailIds, and the response returns a session URL you load inside your application, keeping the signer in your UI from start to finish.

{
  "folderName": "Onboarding - User #4421",
  "sendNow": false,
  "createEmbeddedSigningSession": true,
  "embeddedSignersEmailIds": ["sam@yourapp.com"],
  "signSuccessUrl": "https://yourapp.example.com/signed",
  "fileUrls": ["https://your-storage.example.com/onboarding.pdf"],
  "fileNames": ["onboarding.pdf"],
  "parties": [
    {
      "firstName": "Sam",
      "lastName": "Lee",
      "emailId": "sam@yourapp.com",
      "permission": "FILL_FIELDS_AND_SIGN",
      "sequence": 1
    }
  ]
}

One nuance to expect here. sendNow: false on its own produces a DRAFT folder, but pairing it with createEmbeddedSigningSession returns a folderStatus of SHARED, since the folder has to be live for the session URL to open. No email goes out either way. The response carries an embeddedSigningSessions array, and each entry holds emailIdOfSigner, embeddedToken, and the embeddedSessionURL you render in the next step. Omitting embeddedSignersEmailIds returns email id of embedded signer(s) not submitted, so always list your embedded signers explicitly.

Embedded signing and custom branding

With an embedded signing session, the signer never leaves your application. Load the embeddedSessionURL in an iframe or a dedicated view, with no redirect, no hosted page from another domain, and no disorienting context switch mid-workflow.

An embedded session loaded in-app. The signer completes every field without leaving your product.

The session exposes configurable UI options that give you control over the signing surface:

Custom logo and colors: pass branding parameters at session creation to match your product's visual identity.
Hidden controls: suppress UI elements like the "Add Parties" button when operating in draft or template mode, preventing signers from modifying the recipient list.
Self-sign via API: trigger a signing action programmatically without user interaction, which is useful for automated counter-signature workflows where your system is one of the parties.

For a document where every recipient signs inside your app, createEmbeddedSigningSessionForAllParties set to true covers all of them at once rather than naming each email individually.

sequenceDiagram
    participant App as Your Application
    participant API as Foxit eSign API
    participant Signer as Signer
    App->>API: POST /api/oauth2/access_token<br/>(form-encoded client credentials)
    API-->>App: access_token + instance_url
    App->>API: POST /api/folders/createfolder<br/>(PDF + party definitions)
    API-->>App: folderId + embeddedSessionURL
    App->>Signer: Render embeddedSessionURL in iframe<br/>(no redirect)
    Signer->>API: Complete signing session
    API->>App: POST webhook<br/>(folder_executed event)
    App->>App: Validate HMAC, trigger<br/>CRM update or next workflow step

Webhooks and bulk automation

Polling for document status doesn't scale, and it creates unnecessary load on both sides. Register a webhook endpoint instead, and Foxit eSign will POST an event payload to your server whenever a folder status changes, including the folder_executed event you need to trigger downstream actions.

Registration lives on the eSign portal's API settings page under Configure Webhooks, where you set the callback URL, a webhook secret, and the events you want. Store the secret the platform generates, because it authenticates every inbound event. That page is visible only to the account owner, so an admin-level user will not find it, and your endpoint has to be reachable over public HTTPS.

The owner-only webhook settings. The event checkboxes control which callbacks reach your endpoint.

The events you can subscribe to are folder_sent, folder_viewed, folder_signed, folder_cancelled, folder_executed, folder_deleted, folder_completed, folder_assigned, and folder_access_code_failure. The event to build on is folder_executed. folder_completed fires once every party has signed, but folder_executed fires after Foxit applies the digital signature and locks the audit trail, so it is the point at which a download gives you the final document.

Implement HMAC secret-key validation on your webhook handler before you move to production. Foxit delivers each callback as <your-url>?signature=<base64>, where the signature is the base64 of an HMAC-SHA-256 over the raw request body keyed with your webhook secret. Verify it against the unparsed bytes, since re-serializing the JSON changes whitespace or key order and breaks the comparison. An annotated Python handler shows how each piece fits together:

import base64
import hashlib
import hmac
import os

from flask import Flask, request, jsonify

app = Flask(__name__)
WEBHOOK_SECRET = os.environ["ESIGN_WEBHOOK_SECRET"]  # from the Foxit eSign portal


def verify_signature(raw_body: bytes, signature: str) -> bool:
    # Compute the base64 HMAC-SHA256 of the raw body and compare in constant time
    expected = base64.b64encode(
        hmac.new(WEBHOOK_SECRET.encode(), raw_body, hashlib.sha256).digest()
    ).decode()
    return hmac.compare_digest(expected, signature)


@app.route("/webhook/foxit", methods=["POST"])
def foxit_webhook():
    # Read the unparsed bytes and verify against the signature query parameter
    raw_body = request.get_data()
    if not verify_signature(raw_body, request.args.get("signature", "")):
        return jsonify({"error": "invalid signature"}), 403

    # Signature valid, so parse the event and branch on folder_executed
    payload = request.get_json(silent=True) or {}
    folder = payload.get("data", {}).get("folder", {})
    if payload.get("event_name") == "folder_executed":
        handle_completion(folder.get("folderId"))

    return jsonify({"status": "received"}), 200  # acknowledge before heavy work


def handle_completion(folder_id: str) -> None:
    # Move heavy work to a task queue to keep response times low
    pass

In this handler you read the unparsed body first, recompute the base64 HMAC-SHA256 over those exact bytes with your webhook secret, and compare it against the signature query parameter using hmac.compare_digest so the check runs in constant time and never leaks the correct value one character at a time. A mismatch returns 403 before any business logic runs, which stops a spoofed POST to your public URL from triggering downstream work. Only after the signature passes do you parse the JSON, read event_name from the payload and the folder from its data object, and branch on folder_executed. Return 200 promptly and move handle_completion to a task queue if it touches a database or calls an external API.

For bulk automation, the same API surface scales to thousands of agreements. Define a template once, supply per-recipient field pre-fill values for each signer, and the completion webhook fires individually per recipient, giving you fine-grained control over downstream actions without any polling.

Wrapping up

Authenticate once with the client-credentials grant, create a folder with your PDF and party definitions, choose how it goes out (sendNow for draft versus direct, createEmbeddedSigningSession for in-app signing), and let the folder_executed webhook drive everything that follows. The same patterns that work for a single NDA scale to bulk send campaigns with dynamic per-recipient field values, with no changes to the API surface.

To run these patterns against a live API before wiring them into production, Foxit eSign offers a free developer account with a full API playground, no credit card required. Create one at app.developer-api.foxit.com/sign-up and make your first envelope call in minutes. Which signing workflow has given you the most trouble to integrate? Share your experience in the comments.

Best churn management software in 2026, sorted by the job it actually does

Lucien Chemaly — Wed, 05 Aug 2026 10:32:00 +0000

That is not a bad product. It is a good product bought for the wrong job. And it keeps happening because almost every "best churn management software" list on the internet puts four unrelated categories of product in one ranked column, then compares their prices as though they were alternatives to each other.

Disclosure, since you should weigh the rest of this accordingly. We build Outro, which is one of the tools in the interception category below. I have tried to write the piece I wanted when I was choosing, which means naming the cases where a competitor is the better buy and where Outro is the wrong answer. There is a section near the end doing exactly that.

Every price and feature claim here was checked against the vendor's own pricing page in August 2026. Where a vendor does not publish pricing, this says so rather than estimating.

The four jobs hiding inside "churn software"

Read the current roundups and you will find ChurnZero, Gainsight, Churn Buster, ProsperStack and Pecan AI in a single list. Those products do not compete. They solve four different problems that happen at four different moments.

Measure why churn happened. Reporting after the fact. Tells you the size and shape of the problem.
Intervene at the cancel moment. Sits between the cancel button and the billing provider, asks why, and offers something before the subscription ends.
Recover failed payments. Handles involuntary churn, where the customer never chose to leave and their card simply failed.
Manage accounts before they ever reach a cancel button. Health scores and playbooks for a human success team, which presumes you have one.

A tool built for job 1 cannot do job 2, no matter how good its charts are. A tool built for job 3 is solving a problem that has nothing to do with why customers want to leave. Buying across categories by comparing monthly price is how the founder above ended up with excellent reporting and no saves.

So work out which job you are hiring for first. The rest of this is organised that way.

Job 1: measuring why churn happened

Baremetrics is the reference tool here. It reads your billing data and turns it into MRR, churn rate, LTV and cohort reporting. Its Cancellation Insights add-on collects feedback with in-app popups and automates post-cancel follow-up emails.

The pricing deserves care, because it is the most commonly misquoted number in this category. Baremetrics plans start at $75/mo for Launch, covering $0 to $360K ARR, then $255/mo for Growth and $1,152/mo for Scale. Cancellation Insights and Recover are separate add-ons at $129/mo each, on top of a base plan. Lists that describe Baremetrics as "from $129/mo" for churn purposes are quoting the add-on in isolation. The real floor to get cancellation feedback is $75 plus $129, so a little over $200/mo.

What it does not do is intervene. In-app popups and post-cancel emails reach the customer either side of the decision, not during it. If your goal is a report, this is the right category. If your goal is a save, it is not.

Job 2: intervening at the cancel moment

This is the category most people mean by "churn tool", and it is where the real differences sit. All of these products put a step between the cancel button and the billing provider.

The interception moment. Whatever the tool, this is the screen doing the work, and the design of this one screen decides how much you learn.

Churnkey is the most complete retention suite of the group. Cancel flows, payment recovery and metrics on the entry plan, then A/B testing, segmentation and rules-based retry logic above that, then AI features on the top tier. Its Starter plan is $250 per month billed yearly and is gated by volume, described as available to teams with less than $5k/mo churn volume. Core and Intelligence are quote-only. There is a 14-day trial with no credit card.

Two details matter when you compare it. The volume gate means Starter is explicitly not for teams with larger churn, so growing past $5k/mo monthly churn moves you to a quoted plan. And the AI capabilities, including Feedback AI and AI-powered translations, sit on the Intelligence tier rather than the entry plan, so an AI comparison against Churnkey's cheapest plan is not comparing like with like.

ProsperStack offers hosted, customisable cancellation flows with deep billing integrations. Grow starts at $200/mo and covers 50 to 500 cancel sessions per month, Prosper is $750/mo for 500 or more, and Enterprise is custom. Note that 500 is the ceiling of the Grow band rather than an allowance, which is a distinction several roundups get backwards.

Its A/B testing and AI Autopilot offers begin on Prosper, and multi-language support is Enterprise-only. If you sell in more than one language, ProsperStack's entry tier will not cover you, and that is a pricing question rather than a feature question.

SubJolt is the budget option and is genuinely cheap. Starter is $0/month for up to 50 cancel sessions per month, and Pro is $99/month for unlimited sessions with a 30-day free trial. It integrates with Stripe, Chargebee and Recharge. It offers write-in reason sentiment analysis, though it does not describe that as AI, and it advertises no interface languages. For a small subscription business that wants a cancel flow with offers and does not need much else, the free tier alone makes it worth trying first.

Chargebee Retention is the enterprise end. Pricing is not public and the call to action is a demo request. Two things about it have changed recently enough that most comparisons are out of date. It is now presented as part of Chargebee Growth rather than a standalone product. And it is not restricted to Chargebee billing customers, since its own page describes integrating billing platforms including Chargebee, Recurly and Stripe. It has A/B testing including ML-based smart targeting. If you were avoiding it because you bill through Stripe, that reason no longer holds.

One thing to know if you are researching this category is that brightback.com no longer serves a website. DNS still resolves but the domain returns no HTTP response. Brightback became Chargebee Retention, so any roundup still listing Brightback as a current separate product is working from old notes.

Outro is the tool we build. It replaces the cancel button with a short spoken question, transcribes and classifies the reason with AI, then shows the save offer most likely to work before the cancellation goes through. Plans are $29/mo Starter, $79/mo Pro and $199/mo Scale, with a 14-day trial on every plan and no card required.

The specific bet is that a dropdown loses the information you needed. When somebody picks "too expensive" from a list, you learn nothing you can act on. When they say it out loud, you get the sentence behind it, and those sentences are usually about something other than price.

The output side. Each row is a real spoken answer, transcribed, classified and sentiment-scored, which is the part a fixed dropdown cannot produce.

I checked every vendor in this list for this, and none of the others advertise voice exit interviews. That is the honest scope of the differentiation. It is one capability, not a general claim of superiority, and the sections below are where it stops mattering.

Job 3: recovering failed payments

Involuntary churn is a separate problem with separate tools. The customer did not decide to leave. Their card expired, or a payment failed, and the subscription lapsed. No amount of asking why they cancelled helps, because they did not.

Churn Buster specialises here, and Churnkey includes payment recovery from its entry plan, which is a genuine advantage of buying a suite. Baremetrics sells Recover as a $129/mo add-on.

Outro does not do this at all. If failed payments are your main leak, fix that first, and this article is not about your problem.

Job 4: managing accounts before the cancel button

ChurnZero and Gainsight are customer success platforms for B2B SaaS with named accounts and human CSMs. They track product adoption and account health so a person can intervene weeks before a renewal.

They are excellent and almost certainly irrelevant to a self-serve business. If your customers sign up with a credit card and never speak to anyone, there is no CSM to route a health score to, and the cancel moment is the only conversation you will ever get. That is precisely why the interception category exists.

The comparison, with everything verified

Checked against each vendor's own pricing page in August 2026. "Not advertised" means the vendor does not claim it publicly, which is not the same as absence.

	Entry price	Voice interviews	AI reason detection	Failed-payment recovery	A/B testing	Free option
Outro	$29/mo	Yes	Yes	No	No	14-day trial, no card
Churnkey	$250/mo billed yearly, under $5k/mo churn	No	On Intelligence tier	Yes, entry plan	On Core tier	14-day trial, no card
ProsperStack	$200/mo, 50-500 sessions	No	AI Autopilot on Prosper	Revenue recovery	On Prosper tier	Not advertised
SubJolt	$0 up to 50 sessions, $99/mo unlimited	No	Write-in sentiment, not labelled AI	Smart payment retries	Not advertised	Free tier
Chargebee Retention	Not public, demo	No	Not explicitly	Not mentioned	Yes, incl. ML targeting	Sign up for free
Baremetrics	$75/mo plus $129/mo add-on	No	No	Recover add-on	No	Free trial

The row that should decide most purchases is not price. It is which job the tool does.

When Outro is the wrong choice

Choose Churnkey instead if you need failed-payment recovery, reactivation campaigns and A/B-tested flows in one platform and the budget supports it. Outro has none of those three. A suite you only partly use still beats stitching three tools together for most teams.

Choose ProsperStack or Chargebee Retention instead if A/B testing your cancellation flow is the point. We do not have it. If you have enough cancellation volume to reach significance, testing offer variants will beat any qualitative insight, and you should buy the tool that tests.

Choose SubJolt instead if budget is the binding constraint. Its free tier covers 50 sessions a month at $0. If you are pre-revenue or validating, start there and come back when the reasons matter more than the cost.

Choose Baremetrics instead if what you actually want is subscription analytics. Outro reports on cancellations it handled, and nothing else. It is not an MRR analytics platform and will not replace one.

Do not choose Outro at all if you bill anywhere other than Stripe or Lemon Squeezy. That is a hard constraint, not a roadmap item. No Chargebee, Recurly, Paddle, RevenueCat or App Store. And on Lemon Squeezy, pause and downgrade offers auto-apply but discounts fall back to manual because of a limitation in the Lemon Squeezy API, so a Lemon Squeezy team should expect that manual step.

Three more limits, since they come up after purchase rather than before. Page count is plan-limited, with one cancellation page on Starter, up to five on Pro and unlimited on Scale. There is no conditional branching in the flow, so a follow-up question cannot appear based on which reason a customer picked. And a save is only counted after a 14-day grace window and only if the subscription is still live, which makes our numbers look worse than a tool counting saves at the moment of the click.

How to actually choose

A short procedure that avoids the mistake at the top of this article.

Separate voluntary from involuntary churn. Look at how many cancellations were card failures rather than decisions. If it is most of them, buy job 3 and stop reading.
Decide whether you need a number or a reason. If you cannot say what your top cancellation reason is, no dashboard will tell you, because the categories are supplied by you.
Check the billing constraint before anything else. It eliminates more options faster than price does, and it is not negotiable in any of these tools.
Count your monthly cancel sessions. Most pricing in this category is banded by volume, and the bands are where the surprises live.
Then compare price, within one job, between tools that clear the first four.

If you want to size the problem before shopping, our churn calculator will tell you what a point of monthly churn is worth to you annually, which is usually the number that decides whether any of this is worth buying.

Verified saves rather than claimed ones. A save counts here only after a 14-day grace window and only if the subscription is still active.

Common mistakes

Comparing an entry plan against a competitor's top tier. Churnkey's AI is on Intelligence, ProsperStack's A/B testing is on Prosper, and ProsperStack's multi-language support is Enterprise-only. Comparing feature lists without comparing tiers produces a table that is wrong in both directions.
Quoting add-on pricing as platform pricing. Baremetrics at "$129/mo" is not a thing you can buy on its own.
Assuming Chargebee Retention needs Chargebee billing. It integrates Stripe and Recurly, and this is the single most out-of-date claim in the current roundups.
Trusting any list that has not been re-checked this quarter. Brightback's site is gone and Chargebee Retention has moved under Chargebee Growth, both recently enough that most published comparisons still have it wrong. Ours was checked in August 2026 and will also decay.
Buying interception when your churn is involuntary. Ask what proportion of last month's cancellations were payment failures before you shop at all.

Where this leaves you

The category is four categories. Once they are separated, the choice gets much simpler, because most tools are immediately irrelevant to the job you have.

If your churn is mostly failed payments, buy payment recovery. If you have a success team and named accounts, buy a success platform. If you want reporting, buy analytics and accept that it reports rather than intervenes. And if your customers leave through a cancel button without ever telling you why, the interception category is the only one that gets you a conversation, and the choice inside it comes down to whether you need a full suite, the cheapest option, flow testing, or the actual sentence the customer would have said.

If it is that last one, try Outro free for 14 days with no card. And if one of the other four sections described your situation better, buy that instead. A tool bought for the wrong job is more expensive than the one you did not buy.

Agentic Document Workflows: How to Wire PDF APIs into AI Agents That Actually Work in Production

Lucien Chemaly — Tue, 28 Jul 2026 08:08:22 +0000

The demo works. You send a PDF to GPT-4o, ask it to extract line items, and it returns something that looks like JSON. Then you run it on 500 invoices in staging and watch it hallucinate table rows, drop page-two data entirely, and return different field names on identical documents. By the time you get to 10,000 PDFs a day in production, the failure rate makes the whole approach unusable.

That's the prototype trap. Sending raw PDFs to a vision model gets you coherent prose, but it loses table structure, page coordinates, and element types. The output is nondeterministic, which means your downstream agent can't reliably route on field values, validate totals, or trigger conditional workflows. You end up with a pipeline that works in a notebook and breaks in a queue.

The delta between a demo and a deployable agentic document workflow is almost entirely in how you handle the document layer. The Document AI market is projected to grow from USD 14.66 billion in 2025 to USD 27.62 billion by 2030 at a 13.5% CAGR, and most of that investment is being made precisely because raw LLM extraction doesn't hold up under real operating conditions.

A dedicated, deterministic PDF API layer handles structural extraction and document operations, while the LLM handles reasoning and routing. This article shows you how to build that, specifically how to wire Foxit's PDF Services API into an agent pipeline that's auditable, composable, and designed to run at volume.

1. The Production Gap: Why LLMs Reading PDFs Break at Scale

LLM-based PDF extraction fails in production because vision models reconstruct document structure from visual patterns rather than reading it deterministically. At scale, this produces hallucinated table rows, token cost explosion, schema drift between runs, and no replayable audit trail. A better prompt won't fix any of these:

Hallucinated table rows: When a vision model interprets a multi-column PDF table as image input, it reconstructs structure from visual patterns. On clean PDFs, this is often accurate. On anything with merged cells, rotated text, or embedded watermarks, the model invents rows or merges adjacent data. At 10,000 invoices per day, a 2% hallucination rate is 200 wrong records, and you won't know which ones.
Token cost explosion: A 10-page PDF converted to images for vision input can consume 2,000–4,000 tokens per page depending on resolution. Processing 10,000 documents daily at that rate pushes monthly costs into the tens of thousands of dollars for the extraction step alone, before you've done any reasoning.
No structured output contract: The LLM returns whatever JSON shape seems plausible given the prompt. Field names drift between runs. Tables become arrays of strings on one call and arrays of objects on the next. Downstream validators fail silently because the schema wasn't enforced upstream.
No audit trail: If a contract clause gets misclassified and triggers the wrong workflow, you have no way to replay what the model saw and why it decided what it did. Under HIPAA or SOC 2, "the model just got it wrong" isn't an acceptable incident response.

A clean architectural boundary fixes all four. The PDF API handles structured extraction and document operations deterministically, and the LLM operates on the typed output rather than the raw document. That separation is what makes an agentic document workflow actually workable.

2. What an Agentic Document Workflow Actually Looks Like

An agentic document workflow (ADW) differs from RAG and traditional IDP by maintaining state across multi-step operations, coordinating extraction, retrieval, structured output, and downstream actions in a single orchestrated loop. The agent decides, acts, then decides again based on what the action produced.

LlamaIndex coined the term "Agentic Document Workflows" (ADW) to describe a pattern that goes beyond both RAG and traditional intelligent document processing. RAG retrieves text chunks and generates answers in one pass. Traditional IDP classifies and extracts, then routes to a rules-based engine. The agentic loop layers statefulness on top of both, which is what enables conditional routing, validation, and document generation inside the same pipeline.

The document lifecycle an agent must own in this model spans five stages, from ingest (OCR + structural parse) through extract (typed elements), reason (LLM decision layer), and act (generate, redact, sign, or archive), to emit (append an event trace for auditability). Each stage has a clear owner.

The mistake most teams make is mixing the LLM layer and the PDF API layer. The LLM should never see raw PDF bytes. It should receive typed JSON from the PDF API (table arrays, text blocks with bounding box coordinates, form field values) and make decisions on that structured data. The PDF API owns extraction. The LLM owns understanding.

3. The Core API Operations Agents Need

A production-ready PDF API layer for agentic workflows requires four capabilities, namely deterministic structural extraction that returns typed JSON, template-driven document generation, compliance-grade security operations (flatten, encrypt, redact), and programmatic eSign triggering with a native audit trail.

Structured extraction is the most important. The API should combine OCR, layout recognition, and AI parsing to return typed, element-classified JSON rather than raw text. Foxit's PDF Structural Extraction API extracts twelve different element types (text blocks, tables, form fields, images, and more) and returns them as structured JSON, making the output directly consumable by a downstream LLM or validation step without post-processing. The endpoint is currently in Trial status at schema v1.0.7, so pin your parsers to the version.schema field in the response. The schema can change between versions, and a breaking change will fail silently if you're not checking it.

Document generation: Agents that process documents also need to produce them. Foxit's DocGen API takes a base64-encoded DOCX template and a JSON data payload, merges them, and returns a PDF or DOCX. Before generation, the Analyze Document (Base64) endpoint inspects the template's merge fields, which means you can validate that your data payload covers all required placeholders before sending the generation request, rather than discovering missing fields in the output.
Security operations: Compliance archiving almost always requires flattening (merging annotations and form fields into a static layer), encryption, and sometimes redaction. These need to be callable as discrete API operations. The PDF Services API covers these as separate endpoints.
eSign triggering: If your workflow ends in a signature (contract approval, remittance confirmation, policy acknowledgment), the signing step needs to be a programmatic API call. The eSign API initiates signing workflows and maintains a native audit trail including signer identity, timestamps, and an activity history endpoint you can query. This is the one leg of the pipeline where Foxit provides audit data natively. The rest of the trace you build yourself (more on that in Section 5).

4. Wiring a PDF API into Your Agent: The REST Workflow Pattern

Every Foxit PDF Services API call follows a four-step async pattern (upload, submit, poll, download) that applies uniformly to extraction, OCR, compression, and flattening. Internalize this loop once and you can implement any operation without relearning the integration.

Prerequisites

To run the code in this section and the pipeline in Section 7, you need:

Python 3.8+ with pip and a virtual environment
The requests library
A code editor such as VS Code with the Python extension (PyCharm or any editor works too)
A free Foxit developer account (sign up here, no credit card required) for your client_id and client_secret

Set up the workspace in one shot:

mkdir adw-pipeline && cd adw-pipeline
python3 -m venv .venv && source .venv/bin/activate
pip install requests
export FOXIT_CLIENT_ID="your_client_id"
export FOXIT_CLIENT_SECRET="your_client_secret"

The four-step loop

POST to upload the source document as multipart/form-data to receive a documentId
POST to the operation endpoint (e.g., structural extraction) with the documentId to receive a taskId
GET to poll task status using the taskId until status is COMPLETED or FAILED
GET to download the result by its resultDocumentId (a ZIP holding the structural JSON for extraction, a processed PDF for everything else)

The full extraction loop against the https://na1.fusion.foxit.com base URL using requests:

import io
import json
import os
import time
import zipfile

import requests

BASE_URL = "https://na1.fusion.foxit.com/pdf-services/api"

HEADERS = {
    "client_id": os.environ["FOXIT_CLIENT_ID"],
    "client_secret": os.environ["FOXIT_CLIENT_SECRET"],
}


def upload_pdf(filepath: str) -> str:
    """Upload a PDF and return its documentId."""
    with open(filepath, "rb") as f:
        resp = requests.post(
            f"{BASE_URL}/documents/upload",
            headers=HEADERS,
            files={"file": f},
        )
    resp.raise_for_status()
    return resp.json()["documentId"]


def start_extraction(document_id: str) -> str:
    """Submit a structural extraction task and return the taskId."""
    resp = requests.post(
        f"{BASE_URL}/documents/pdf-structural-extract",
        headers={**HEADERS, "Content-Type": "application/json"},
        json={"documentId": document_id},
    )
    resp.raise_for_status()  # 202 Accepted
    return resp.json()["taskId"]


def poll_until_done(task_id: str, interval: int = 3, timeout: int = 120) -> str:
    """Poll task status until COMPLETED, then return the resultDocumentId."""
    deadline = time.time() + timeout
    while time.time() < deadline:
        resp = requests.get(
            f"{BASE_URL}/tasks/{task_id}",
            headers=HEADERS,
        )
        resp.raise_for_status()
        data = resp.json()
        if data["status"] == "COMPLETED":
            return data["resultDocumentId"]
        if data["status"] == "FAILED":
            raise RuntimeError(f"Extraction failed: {data}")
        time.sleep(interval)
    raise TimeoutError(f"Task {task_id} did not complete within {timeout}s")


def download_structure(result_document_id: str) -> dict:
    """Download the result ZIP and return the parsed structural JSON."""
    resp = requests.get(
        f"{BASE_URL}/documents/{result_document_id}/download",
        headers=HEADERS,
    )
    resp.raise_for_status()
    with zipfile.ZipFile(io.BytesIO(resp.content)) as zf:
        return json.loads(zf.read("StructureInfo.json"))


def extract_pdf(filepath: str) -> dict:
    doc_id = upload_pdf(filepath)
    task_id = start_extraction(doc_id)
    result_doc_id = poll_until_done(task_id)
    return download_structure(result_doc_id)

In this code, you upload the source PDF to receive a documentId, submit the structural extraction task against documents/pdf-structural-extract (the API answers 202 Accepted with a taskId), poll the task endpoint every 3 seconds until the status flips to COMPLETED, then download the result document. The result arrives as a ZIP containing StructureInfo.json (the typed structural output) plus a rendered PNG of each page, so download_structure unpacks the archive in memory and returns the parsed JSON. A FAILED status surfaces as a RuntimeError instead of being silently retried.

For DocGen, the same upload-submit-poll-download shape applies conceptually, though the Base64 endpoint used in Section 7 is synchronous and returns the rendered document in the response body.

Scaling the async model: The PDF Services API doesn't offer webhook callbacks. For high-volume workloads at 10,000+ PDFs per day, a poll loop that blocks your agent threads will become a bottleneck. Use a job queue (SQS, Celery, Redis Streams) where each worker owns the poll loop for its assigned task, then calls the agent's reasoning step only after the extraction result is available. The eSign API is the Foxit product with native webhook support for event-driven callbacks. PDF Services is async polling only.

5. Event-Sourced AI: Building an Auditable Agent Trace

Event sourcing solves the agentic pipeline audit problem by capturing every AI decision as an immutable, append-only log entry keyed to a stable document ID. Every processing step (extraction, validation, generation, signing) becomes a replayable event with typed inputs, the policy version that governed the decision, and the output.

Consider a failure mode that won't surface until you're in an audit. An agent misclassified a contract clause as non-binding, triggered the wrong approval workflow, and now you need to demonstrate exactly what inputs the agent saw and what policy it applied. Without that capture, you're reconstructing from logs and guessing.

Event sourcing captures every state change in a system as an immutable event appended to a log. For an agent pipeline, that means every AI decision step appends a record containing its inputs, the policy or prompt version used, and the output. The log is append-only and keyed by a stable document_id. You can replay any document's processing history, re-run a specific step with a changed policy, and produce a per-document audit trail on demand.

Foxit's task-based API architecture gives you clean event boundaries to log. Each operation returns a typed payload, a taskId, and a status, and those are the natural checkpoints where you append events. The eSign API contributes a native audit trail for the signing leg (signer identity, timestamps, and a queryable activity history endpoint), which is the one part of the pipeline you don't have to instrument yourself.

The rest of the trace is yours to build. A minimal event schema needs five fields:

document_id: the stable key every event is grouped under
event_type: e.g., extraction_completed, validation_passed, document_generated
timestamp: when the event was appended
payload: the API response or LLM output for the step
policy_version: the prompt hash or policy ID that governed the decision

Write this to a Postgres table with id SERIAL, document_id UUID, event_type TEXT, payload JSONB, policy_version TEXT, created_at TIMESTAMPTZ DEFAULT NOW(). That's enough to replay any document through the pipeline and produce a per-event audit log.

A naive LLM pipeline leaves intermediate states opaque and non-replayable. A deterministic PDF API layer combined with an append-only event log links every decision to its source data so you can reconstruct it on demand. That's what makes HIPAA, SOC 2, or GDPR audits tractable.

6. MCP as the Agent-Native Integration Layer

The Model Context Protocol (MCP) exposes PDF API tools directly to LLM agent hosts (Claude Desktop, VS Code, Cursor) without custom wrapper code. Foxit's open-source MCP Server ships 35+ callable tools and authenticates via three environment variables, making it the fastest path from agent host to production PDF operations.

The Model Context Protocol (MCP) is an emerging open standard for exposing tool APIs to LLM-based agents. The agent host calls tools by name, the MCP server handles the underlying API calls, and typed results come back ready for the agent's context window, without custom wrapper code.

Foxit publishes an open-source MCP Server that exposes the PDF Services API as 35+ callable tools. It ships in Python (FastMCP framework, Python 3.11+, uv) and TypeScript (pnpm) variants, and authenticates via three environment variables (FOXIT_CLOUD_API_CLIENT_ID, FOXIT_CLOUD_API_CLIENT_SECRET, and FOXIT_CLOUD_API_HOST). Any MCP-compatible host (Claude Desktop, VS Code with GitHub Copilot, Cursor) can connect to it. If you're already using one of those hosts, you can call PDF tools without writing any wrapper code at all.

There's a genuine tradeoff, though. MCP eliminates custom integration work by adding a protocol hop and some latency overhead. For latency-sensitive, high-volume pipelines at the scale described in Section 4, direct REST calls with your own job queue are the right call. Use MCP when you want to iterate fast or when your agent host is already MCP-native and the overhead doesn't matter.

For full installation steps, the complete tool catalog, and host configuration for Claude Desktop and Cursor, see the dedicated guide, Foxit MCP Server: Give AI Agents Direct Access to 30+ PDF Tools via Model Context Protocol.

7. Build This Today: A Minimal Agentic Invoice Processing Pipeline

A production-ready agentic invoice processing pipeline takes six steps, starting from a free developer account and ending in an optional eSign approval, with every step appended to an audit log. It ingests a PDF invoice, extracts line items as structured JSON, validates totals with an LLM reasoning step, and generates a remittance PDF confirmation using the DocGen API. You can implement this against your own documents this week.

Step 1: Create a free Foxit developer account. The free Developer plan gives you 500 credits per year with no credit card required. Your Client ID and Client Secret are available immediately from the dashboard.
Step 2: POST your invoice PDF to the upload endpoint and capture the documentId. If you don't have an invoice handy, use this sample invoice PDF, the same document the output below was extracted from.

The sample invoice the pipeline ingests. The line item table is what structural extraction returns as a typed table element in Step 3.

Step 3: POST to the PDF Structural Extraction endpoint with the documentId. Poll until COMPLETED, then download the result ZIP and read StructureInfo.json (the extract_pdf function from Section 4 does all of this). The JSON types every element it detects, so the invoice's line item table arrives as a structured table element with typed cells, not as a block of text you then need to parse. Here is the output for the sample invoice, trimmed to one cell per concept:

{
  "analyzeResult": {
    "version": {
      "schema": "1.0.7",
      "software": "FoxitPDFAnalyzer",
      "model": "idp-analysis"
    },
    "pages": [
      {
        "pageNumber": 1,
        "size": { "width": 612, "height": 792, "unit": "point" },
        "state": "success"
      }
    ],
    "elements": [
      {
        "type": "title",
        "content": {
          "text": "INVOICE",
          "style": { "fontFamilyName": "Arial", "fontSize": 24.0 }
        },
        "region": { "page": 1, "boundingBox": [90, 71, 189, 71, 189, 99, 90, 99] },
        "score": 0.88,
        "id": "title1"
      },
      {
        "type": "paragraph",
        "content": { "text": "Invoice Number: INV-2025-0042" },
        "region": { "page": 1, "boundingBox": [90, 187, 254, 187, 254, 200, 90, 200] },
        "score": 0.87,
        "id": "paragraph3"
      },
      {
        "type": "table",
        "content": {
          "body": {
            "rowCount": 7,
            "columnCount": 5,
            "cells": [
              {
                "paragraph": {
                  "type": "paragraph",
                  "content": { "text": "Description" },
                  "id": "paragraph7"
                },
                "rowIndex": 0,
                "columnIndex": 1,
                "rowSpan": 1,
                "columnSpan": 1,
                "region": { "page": 1, "boundingBox": [171, 286, 258, 286, 258, 301, 171, 301] }
              },
              {
                "paragraph": {
                  "type": "paragraph",
                  "content": { "text": "$1,560.00" },
                  "id": "paragraph15"
                },
                "rowIndex": 1,
                "columnIndex": 4,
                "rowSpan": 1,
                "columnSpan": 1,
                "region": { "page": 1, "boundingBox": [430, 300, 517, 300, 517, 328, 430, 328] }
              }
            ]
          }
        },
        "regions": [{ "page": 1, "boundingBox": [82, 285, 519, 285, 519, 422, 82, 422] }],
        "id": "table1"
      }
    ]
  }
}

Pin your parser to analyzeResult.version.schema. The schema is at v1.0.7 and the endpoint is in Trial. Version increments are your signal to check for breaking changes.

Step 4: Pass the table JSON to your LLM agent. The prompt becomes a structured data validation task ("do the line item totals equal the invoice total?") rather than an OCR interpretation task. The LLM operates on typed data, not image pixels.
Step 5: POST the validated JSON plus a DOCX remittance template to the DocGen Generate Document (Base64) endpoint. A ready-made remittance template, verified end-to-end against the live API, matches the sample invoice's data.

The remittance template's merge tokens. Note that {{TableStart:line_items}} and {{TableEnd:line_items}} sit in the same table row, which is required for the loop to render. Run the Analyze Document (Base64) endpoint first to confirm your template's merge fields match your data payload, and keep the template under the endpoint's 4 MB post-base64 cap (compress embedded images in Word's Picture Format pane if you hit it). Receive the output PDF.

The remittance PDF generated from the template and the validated invoice data, rendered by the live DocGen API. Your Step 5 output should match this.

Step 6 (optional): POST to the eSign API to route the remittance for approval. The API creates a signing folder, notifies signers, and maintains the activity history audit trail.

Every step in this pipeline produces a discrete event with a typed payload. Append each one to your audit log. You end up with a complete, replayable record of what was extracted, what the agent decided, and what was generated, for every document that passes through the system.

Frequently Asked Questions

What is an agentic document workflow, and how does it differ from RAG?
An agentic document workflow (ADW) maintains state across multi-step operations and coordinates document processing, retrieval, structured output, and downstream actions in a single orchestrated loop. RAG retrieves text and generates a response in one pass. An ADW agent decides, acts, and then decides again based on what each action produced, enabling conditional routing, validation, and document generation within the same pipeline.

Why does sending raw PDFs to a vision model fail at scale?
Vision models reconstruct document structure from visual patterns rather than reading it deterministically. At 10,000 documents per day, even a 2% hallucination rate produces 200 wrong records, and you won't know which ones. Field name drift between runs breaks downstream validators, and there's no replayable audit trail when a misclassification triggers the wrong workflow.

How does a dedicated PDF API layer fix the production delta?
A dedicated PDF API like Foxit's PDF Services API extracts structure deterministically, returning typed JSON with twelve element types, bounding boxes, and form field values, rather than reconstructing it from pixels. The LLM then operates on that typed output rather than raw bytes, making the extraction step auditable, schema-consistent, and cost-predictable.

What is the async polling pattern in the Foxit PDF Services API?
Every operation follows the same four-step loop. POST to upload the document (returns a documentId), POST to the operation endpoint (returns a taskId), GET to poll status until COMPLETED or FAILED, then GET to download the result by its resultDocumentId. This pattern applies uniformly across extraction, OCR, compression, and flattening.

When should I use the Foxit MCP Server instead of direct REST calls?
Use the MCP Server when you're already in an MCP-native host (Claude Desktop, Cursor, VS Code with Copilot) and want to call PDF tools without writing wrapper code. Use direct REST calls with a job queue (SQS, Celery, Redis Streams) for latency-sensitive, high-volume pipelines where the protocol hop overhead matters.

How do I build an auditable trace for an AI document pipeline?
Implement event sourcing, where every AI decision step appends an immutable record to an append-only log containing document_id, event_type, timestamp, payload, and policy_version. Foxit's task-based API provides clean event boundaries, and each taskId response is a natural checkpoint. The eSign API contributes a native audit trail for the signing leg. The rest you instrument yourself.

Does the Foxit PDF Structural Extraction API schema change between versions?
Yes. The endpoint is currently in Trial status at schema v1.0.7, and the schema can change between version increments. Always pin your parsers to the analyzeResult.version.schema field in the response and check the Trial API reference when you see a version bump, or a breaking change will fail silently.

Final Thoughts

The delta between a working demo and a production agentic document workflow comes down to one architectural decision. Does your PDF layer produce deterministic, typed output? A vision model reconstructing structure from pixels doesn't scale. A dedicated extraction layer does.

Foxit's PDF Services API, DocGen API, and eSign API cover the full document lifecycle (extraction, generation, security operations, and signing) through a consistent REST pattern your agents can call reliably at volume. Add an append-only event log on top of those clean API boundaries and you have the auditability story that compliance teams and incident response actually require.

To test the extraction-to-generation pipeline against your own documents, create a free Foxit developer account (500 credits, no credit card required). The full API reference is at developer-api.foxit.com.

What document type are you trying to automate in your current pipeline, and which step is giving you the most friction? Drop it in the comments.

Building Event-Driven Manufacturing Microservices with Redpanda Connect

Lucien Chemaly — Tue, 21 Jul 2026 07:06:51 +0000

Modern manufacturing environments generate an immense stream of events from programmable logic controllers (PLCs), supervisory control and data acquisition (SCADA) systems, edge sensors, and quality inspection devices. On the shop floor, Message Queuing Telemetry Transport (MQTT) has become the dominant protocol for moving this telemetry between devices and systems. Its publish-subscribe model lets sensors push data to central brokers without needing to know who consumes it, and its lightweight design keeps memory and CPU usage low enough to run on the most constrained embedded hardware.

Collecting events, however, only solves part of the problem. The data still needs to be interpreted as it arrives. I wanted to see if you could catch a quality breach or a bearing about to fail the moment the reading came in, using nothing but off-the-shelf MQTT and Redpanda Connect and no custom middleware. Batch-oriented systems and periodic ERP polling are fine for a lot of manufacturing use cases, but not for that.

In this tutorial, I'll show you how to build a complete, runnable pipeline that:

Simulates sensor telemetry and publishes it via MQTT.
Ingests those events into Redpanda through Redpanda Connect, using its built-in MQTT input.
Routes enriched events to domain-specific Redpanda topics.
Powers three Python microservices (quality SPC, predictive maintenance, and a live dashboard) that consume events and produce alerts.

Prerequisites

Before you begin, make sure you have the following installed and running:

Tool	Details	Check Command
Docker Desktop	Includes Docker Engine and Docker Compose. Make sure it is running before you start	`docker compose version`
Python	3.10 or later	`python3 --version`
pip	Comes with Python, used to install project dependencies	`pip3 --version`

macOS note: Port 5000 is often used by AirPlay Receiver. The dashboard service defaults to port 5050 to avoid this conflict. If you want to use a different port, set HTTP_PORT when starting the dashboard.

Understanding the Role of Microservices in Modern Manufacturing

Traditional monolithic manufacturing execution systems (MES) combine quality control, machine management, job scheduling, and reporting into a single application. When high-frequency telemetry must be processed in milliseconds, these monoliths hit their limits. If you integrate a new sensor on a specific line, you have to fully redeploy the entire application. A bug in the new integration can cascade into unrelated functions.

Microservices address this by decoupling the monolith into independent, specialized services:

A quality service for measurements and SPC tolerances.
A maintenance service for predictive analytics on vibration and temperature data.
A dashboard service for real-time KPIs.

Each is developed, deployed, and scaled independently. The quality team can ship a new surface-inspection algorithm while the maintenance team simultaneously improves a bearing-wear model, with no shared deployment windows and no cross-team regression risk.

These advantages hinge on real-time event processing. When a quality measurement falls outside SPC limits, the system must alert operators and potentially halt the line within seconds, before hundreds of defective parts are produced. Delays of even a few minutes, typical of batch processing or periodic database queries, can result in costly scrap and machine damage.

Redpanda enables real-time event processing, designed for high-throughput, low-latency workloads. MQTT data flows through Redpanda Connect into topics where microservices consume it independently, creating a standardized ingestion path that eliminates point-to-point integrations. New services simply subscribe to the relevant topics.

Why MQTT for Shop-Floor Ingestion

Edge devices and PLCs often have limited computing capacity and memory. MQTT requires minimal resources and runs efficiently on even the most constrained hardware. This is important when thousands of sensors transmit data simultaneously across a factory floor.

MQTT's publish/subscribe model fits event-driven architecture naturally. Sensors publish readings to hierarchical topics such as factory/line1/machine-01/temperature or factory/line1/machine-02/vibration without knowing which services consume the data. Adding a new analytics service doesn't require a sensor reconfiguration because the service simply subscribes to the relevant topic tree.

MQTT's quality-of-service levels guarantee delivery even after temporary outages, which is essential in environments where metal structures and electromagnetic interference frequently disrupt connectivity.

Redpanda Connect provides a built-in MQTT input that pulls telemetry directly into Redpanda topics. Sensor data flows into the central event backbone without additional middleware or custom code, and no intermediate databases or REST APIs slow down the data path. Some deployments use MQTT-native brokers built on Redpanda (e.g., Waterstream) to consolidate broker and streaming layers for multi-factory setups.

Event Modeling and Stream Processing Patterns

Before writing any code, it helps to think about how topics, payloads, and delivery guarantees shape the system.

Designing Topics

Topic structure directly influences performance and maintainability. There are two common strategies:

Physical hierarchy (factory/line1/machine-01/temperature) is used when services focus on specific equipment or locations. A line-specific dashboard subscribes to factory/line1/# to receive only relevant data.
Functional domains (quality.measurements, maintenance.telemetry) are used when services focus on business functions. A quality service analyzing defects across all lines subscribes to a single topic.

I used physical hierarchy for MQTT ingestion here since it matches how the simulator already publishes data, then let Redpanda Connect's routing logic fan events out into functional Redpanda topics for the services that consume them.

The JSON format is human-readable and easy to debug. For production environments generating millions of events daily, Avro with Redpanda's Schema Registry offers schema evolution and compact serialization. Before a producer can publish data with a changed schema, the registry validates backward compatibility, preventing deployments that break downstream consumers.

Partition keys: Using machine_id as the message key ensures all events from a given machine land in the same partition, preserving ordering for time-dependent analyses like trend calculations and SPC windows.

Stream Processing Patterns

Pattern	Use Case	Example
Windowed aggregation	Continuous KPI calculation	A five-minute rolling window computes machine utilization for OEE dashboards
Complex event processing	Anomaly detection from correlated streams	Temperature rising above baseline while vibration increases triggers a predictive maintenance alert
Enrichment	Adding business context to raw telemetry	A compacted topic containing machine specifications provides tolerance limits without database lookups

Beyond processing patterns, teams must also decide how events are delivered and acknowledged across the system.

Delivery Semantics Trade-offs

At-least-once: No events are lost; duplicates are possible. Choose this for monitoring and alerting where a duplicate notification is acceptable, but missing a warning is not.
Exactly-once: Each event is processed exactly once, at the cost of higher latency and resource consumption. Use this for inventory counts, production totals, or financial calculations where duplicates skew results.
Event replay: Redpanda retains events with configurable retention (commonly 7–30 days). Engineers can reprocess historical events for root-cause analysis of intermittent failures.

Architecture Overview

The end-to-end pipeline looks like this:

Project Structure

To understand the project structure, clone the repository and look at the layout:

`bash git clone https://github.com/See4Devs/event-driven-redpanda.git cd event-driven-redpanda`

The repository contains three infrastructure configuration files at the root and four service directories, each with its own Python entry point and dependencies:

| event-driven-redpanda/ |-- docker-compose.yml # Orchestrates Redpanda, Mosquitto, Connect, Console |-- mosquitto.conf # Mosquitto broker config (anonymous access for dev) |-- connect.yaml # Redpanda Connect MQTT-to-Redpanda pipeline | |-- sensor_simulator/ | |-- simulator.py # Publishes fake MQTT telemetry for 3 machines | +-- requirements.txt # paho-mqtt | |-- quality_service/ | |-- service.py # SPC rolling-window breach detection -> alerts | +-- requirements.txt # confluent-kafka | |-- maintenance_service/ | |-- service.py # Vibration threshold anomaly detection -> alerts | +-- requirements.txt # confluent-kafka | +-- dashboard_service/ |-- service.py # Last-known-state HTTP API (Flask) +-- requirements.txt # confluent-kafka, flask |
| :---- |

Here is what each component does:

docker-compose.yml: Defines the infrastructure: a single-node Redpanda broker, the Redpanda Console web UI, an Eclipse Mosquitto MQTT broker, a Redpanda Connect pipeline container, and a one-shot topic-setup container that creates the six Redpanda topics on startup.
mosquitto.conf: Minimal Mosquitto configuration that listens on port 1883 with anonymous access (suitable for local development).
connect.yaml: Declarative Redpanda Connect pipeline. Subscribes to MQTT topic factory/line1/#, enriches payloads with ingestion metadata, and routes events to domain-specific Redpanda topics based on sensor_type using Bloblang expressions.
sensor_simulator/: Python script that publishes fake telemetry for three machines (machine-01, machine-02, machine-03), each with three sensor types (temperature, vibration, pressure), to MQTT topics following the pattern factory/line1/<machine_id>/<sensor_type>. A five percent anomaly injection probability simulates real-world spikes.
quality_service/: Consumes temperature and pressure events from quality.measurements, maintains a per-machine, per-sensor rolling window (default 30 readings), and publishes alerts to quality.alerts when a reading breaches the mean +/- 3 sigma threshold (simplified Western Electric Rule 1).
maintenance_service/: Consumes vibration events from maintenance.telemetry and applies threshold-based anomaly detection: WARNING when the rolling average exceeds 3.0 mm/s, CRITICAL when any single reading exceeds 5.0 mm/s. Publishes alerts to maintenance.alerts.
dashboard_service/: Consumes from all measurement and alert topics to build a last-known-state view of every machine in memory (the "digital twin" pattern), then serves it over a Flask HTTP API on port 5050.

Building the Pipeline: Step by Step

With the project cloned and the file layout in place, you can now walk through each component from infrastructure to application code.

Install Python Dependencies

From the project root, install the dependencies for all four services:

`bash pip3 install -r sensor_simulator/requirements.txt \ -r quality_service/requirements.txt \ -r maintenance_service/requirements.txt \ -r dashboard_service/requirements.txt`

This installs paho-mqtt, confluent-kafka, and flask.

Start the Infrastructure

Start all containers in the background:

`bash docker compose up -d`

This brings up five containers:

Container	Purpose	Exposed Port
`redpanda`	Kafka-compatible streaming broker	`19092` (Kafka API), `18082` (HTTP Proxy), `18081` (Schema Registry)
`redpanda-console`	Web UI for inspecting topics and messages	`8080`
`mosquitto`	MQTT broker for sensor ingestion	`1883`
`redpanda-connect`	MQTT-to-Redpanda pipeline	none
`topic-setup`	One-shot container that creates Redpanda topics, then exits	none

Wait a few seconds for the healthchecks to pass, then verify the topics exist:

`bash docker exec redpanda rpk topic list`

You should see all six topics:

`NAME PARTITIONS REPLICAS dashboard.state 3 1 maintenance.alerts 1 1 maintenance.telemetry 3 1 quality.alerts 1 1 quality.measurements 3 1 sensor.raw 3 1`

Note: The sensor.raw topic will remain empty during this tutorial. The simulator only produces temperature, vibration, and pressure readings, all of which are explicitly routed to quality.measurements or maintenance.telemetry. The sensor.raw topic acts as a catch-all for any unrecognized sensor types, ensuring unknown events are captured rather than dropped.

You can also open Redpanda Console in your browser to visually inspect topics and messages as they flow through the system. See the Redpanda Console documentation for a full feature overview.

Understand the Redpanda Connect Pipeline

Before starting the simulator, take a moment to review the connect.yaml file that is already running inside the redpanda-connect container. Here it is in full:

| yaml input: mqtt: urls: - tcp://mosquitto:1883 topics: - "factory/line1/#" client_id: "redpanda-connect-ingest" qos: 1 pipeline: processors: # Step 1: Parse the raw JSON payload - mapping: | root = this # Step 2: Add ingestion metadata - mapping: | root = this root.ingested_at = now() root.pipeline = "redpanda-connect" # Step 3: Route to topic based on sensor_type - mapping: | let st = this.sensor_type.lowercase() root = this meta target_topic = match $st { "temperature" => "quality.measurements", "pressure" => "quality.measurements", "vibration" => "maintenance.telemetry", _ => "sensor.raw", } output: kafka: addresses: - redpanda:9092 topic: ${! meta("target_topic") } key: ${! json("machine_id") } partitioner: fnv1a_hash max_in_flight: 64 |
| :---- |

Here are the key points:

input.mqtt.topics uses factory/line1/#. The # is MQTT's multi-level wildcard, subscribing to all sensors on line 1 regardless of machine or sensor type.
Pipeline.processors uses Bloblang mapping expressions. The match expression routes temperature/pressure events to quality.measurements, vibration events to maintenance.telemetry, and everything else to sensor.raw.
meta target_topic sets a metadata field that the output.kafka.topic field interpolates with ${! meta("target_topic") }.
output.kafka points at redpanda:9092 because Redpanda is Kafka API-compatible. Standard Kafka clients and Redpanda Connect's Kafka output work directly against Redpanda without modification.

The following diagram shows how MQTT topics flow through the Redpanda Connect pipeline and get routed to their respective Redpanda topics:

Simulate Sensor Telemetry

The sensor simulator publishes fake readings for three machines, each with three sensor types (temperature, vibration, pressure). Run it from the project root:

`bash python3 sensor_simulator/simulator.py`

Your output will look like this:

`Sensor simulator connected to localhost:1883 Publishing every 2.0s for machines: ['machine-01', 'machine-02', 'machine-03'] -> factory/line1/machine-01/temperature: 72.34 celsius -> factory/line1/machine-01/vibration: 1.45 mm_s -> factory/line1/machine-01/pressure: 5.12 bar -> factory/line1/machine-02/temperature: 71.89 celsius`

Each message is a JSON payload with this schema:

`json { "event_id": "a1b2c3d4-...", "machine_id": "machine-01", "sensor_type": "temperature", "value": 72.34, "unit": "celsius", "timestamp": "2025-01-15T10:30:00.000Z", "line": "line1", "factory": "factory-north" }`

Open Redpanda Console and navigate to the Topics tab. You should see messages flowing into quality.measurements and maintenance.telemetry.

Tip: Leave the simulator running in its own terminal window. Open new terminal windows for the following services.

Run the Quality SPC Service

Open a new terminal. This microservice consumes temperature and pressure events from quality.measurements, maintains a rolling window per machine per sensor, and publishes an alert to quality.alerts when a reading breaches the mean +/- 3 sigma threshold (simplified Western Electric Rule 1).

`bash python3 quality_service/service.py`

Output:

When the simulator injects an anomalous spike (five percent probability), the SPC check fires and produces an alert event:

`json { "alert_id": "...", "alert_type": "SPC_BREACH", "machine_id": "machine-03", "sensor_type": "temperature", "value": 92.15, "mean": 72.01, "stdev": 1.48, "z_score": 3.41, "sigma_threshold": 3.0, "window_size": 30, "timestamp": "2025-01-15T10:31:05.000Z" }`

Run the Predictive Maintenance Service

Open another terminal. This service consumes vibration events from maintenance.telemetry and applies threshold-based anomaly detection:

WARNING: rolling average exceeds 3.0 mm/s.
CRITICAL: any single reading exceeds 5.0 mm/s.

I picked 3.0/5.0 mm/s somewhat arbitrarily for this demo, but in a real deployment you'd tune these against your specific machine baselines. In a production system, this calls an ML inference endpoint. The threshold approach keeps the tutorial self-contained.

`bash python3 maintenance_service/service.py`

Output:

Run the Dashboard Service

Open one more terminal. The dashboard service materializes the last-known state of every machine by consuming all measurement and alert topics, then exposes an HTTP API:

`bash python3 dashboard_service/service.py`

Once it's running, query it:

| bash # All machines and their latest sensor readings curl -s http://localhost:5050/machines | python3 -m json.tool # Detail for a specific machine curl -s http://localhost:5050/machines/machine-01 | python3 -m json.tool # Recent alerts across all machines curl -s http://localhost:5050/alerts | python3 -m json.tool |
| :---- |

Here's an example response from /machines:

`json { "machine-01": { "temperature": { "value": 72.34, "unit": "celsius", "timestamp": "...", "topic": "quality.measurements" }, "vibration": { "value": 1.23, "unit": "mm_s", "timestamp": "...", "topic": "maintenance.telemetry" }, "pressure": { "value": 5.12, "unit": "bar", "timestamp": "...", "topic": "quality.measurements" } }, "machine-02": { "..." }, "machine-03": { "..." } }`

This is the "digital twin" pattern: a continuously updated materialized view in memory, rebuilt entirely from the event stream without relying on an external database.

Where Change Data Capture Still Makes Sense

Event-driven microservices excel at processing real-time MQTT streams, but many factories also run established enterprise systems that were not designed for event-driven architecture. ERP, MES, and warehouse management systems (WMS) store their data in relational databases.

Change data capture (CDC) helps bridge this gap. When a work order is released or inventory is adjusted, these changes occur as database transactions. Redpanda Connect supports CDC connectors for PostgreSQL, MySQL, and MongoDB that capture these deltas and publish them as events automatically.

A minimal CDC configuration for PostgreSQL with Redpanda Connect looks like:

`yaml input: postgres_cdc: dsn: "postgres://user:pass@erp-db:5432/manufacturing?sslmode=disable" schema: "public" tables: - work_orders - inventory snapshot: true output: kafka: addresses: - redpanda:9092 topic: 'erp.${! meta("table") }' key: ${! json("id") }`

Important: CDC should be used sparingly and exclusively for system-of-record deltas from transactional systems. Sensor streams, machine telemetry, and production events must remain event-native. CDC is not suitable for high-frequency time-series data because it is optimized for relational change capture, not continuous streams.

Cleanup

When you are done experimenting, stop the Python services with Ctrl+C in each terminal, then tear down the Docker infrastructure:

`bash docker compose down -v`

The -v flag removes the named volume (redpanda-data), freeing disk space. Omit it if you want to preserve topic data between runs.

All the code used in this tutorial is available on GitHub.

Conclusion

In this tutorial, you built a sensor-first, event-driven manufacturing pipeline end to end. MQTT telemetry flows from simulated machines through an Eclipse Mosquitto broker, where Redpanda Connect ingests, normalizes, and routes events into domain-specific Redpanda topics. Three independent Python microservices (quality SPC, predictive maintenance, and a live dashboard) consume these events and produce alerts or materialized views. The entire stack runs locally with Docker Compose.

I liked this setup because it took very little custom code to get there. The routing logic lives in a single Bloblang mapping in connect.yaml, and each microservice only has to worry about its own topic. Where legacy systems like ERP or MES aren't yet event-native, CDC connectors bridge the gap without forcing sensor data through the same relational path.

Build an Automated PDF Generation Pipeline: From Word Template to Signed Document

Lucien Chemaly — Fri, 10 Jul 2026 06:51:33 +0000

The first time you spin up Puppeteer and call page.pdf(), it feels solved. You get a PDF. It renders. Ship it.

That decision comes back to haunt you when you're generating 500 contracts a day, your designer updated the brand template and nobody propagated the change, compliance wants audit-ready flat files, and legal is asking why the e-signatures aren't attached to the archived copies. What started as a utility function is now load-bearing infrastructure, and the duct tape is showing.

Headless-browser rendering gives you a PDF with no template management, no compliance-grade output, and no downstream handoff. Those things require a different design. This guide walks through that design, a three-stage pipeline covering data binding from a Word template, synchronous document generation, post-processing for compliance and delivery, and an eSign handoff, all through REST APIs.

Why "Just Use Puppeteer" Breaks at Scale

Puppeteer works. At low volume, with a single developer maintaining the rendering code, it's perfectly reasonable. The cracks appear when you add real-world pressure.

The first problem is template drift. When your HTML template lives in a repository owned by engineers, every brand update requires a PR, a review, and a deploy. Product managers can't touch it. Designers can't touch it. The template ends up frozen in a past state of the brand because the cost of updating it is higher than the cost of tolerating the inconsistency.

The second problem is rendering inconsistency. Headless Chrome's output changes between Chrome versions. Fonts render differently depending on what's installed on the host OS. Your CI/CD environment produces slightly different PDFs than your local machine. For documents that are legally significant (contracts, invoices, disclosures), "slightly different" is not acceptable.

The third problem is the compliance delta. page.pdf() produces a valid PDF, but it gives you no flattened file for archival compliance, no linearized file for web serving, and no audit trail. Those capabilities don't exist in Puppeteer. You bolt them on separately, and each bolt is a seam where something can break.

A production document pipeline needs reproducible data binding (the same input produces consistent, deterministic output), compliance-ready output formats (flat, archivable, signable files), and downstream handoff (delivering documents into signing workflows, storage systems, or portals). A headless browser covers none of these, so each one becomes a separate integration you own and maintain.

Pipeline Architecture: What You're Actually Building

The pipeline has three stages. Understanding them before writing any code prevents the most common integration mistakes.

Stage 1 is the data source. Your CRM, ERP, database, or internal service provides a JSON payload containing the values that populate the document. Business logic lives here, including field mapping, conditional logic for what sections to include, and data validation before any API call goes out.

Stage 2 is document generation. A Word template defines the document structure, and the generation API merges the JSON payload into it, producing a PDF or DOCX. You POST, you get back a document.

Stage 3 is post-processing and delivery. The generated PDF moves into a processing pipeline for compliance operations (flatten for archiving, linearize for web delivery, compress for storage), then hands off to an eSign workflow or an archive system.

The synchronous versus asynchronous split is the architectural decision with the biggest impact on integration complexity. The Document Generation API runs synchronously, so you POST a request and receive the rendered document in the response body, with no job IDs and no polling. That fits naturally into request-response backend workflows, such as generating a contract when a user clicks "Send Agreement" in your CRM. PDF Services operations (flatten, linearize, compress) run asynchronously, so you submit a job, get a task ID, and poll for completion. The DocGen response is immediate, but the post-processing chain adds latency you need to account for in your design.

Authentication is consistent across all three stages. Every request includes client_id and client_secret as request headers, retrieved from the developer dashboard after creating your account. The base host for both DocGen and PDF Services in these examples is https://na1.fusion.foxit.com; your dashboard shows the host assigned to your account. Store the credentials as environment variables, not in source code. The full request and response schema for every endpoint used below lives in Foxit's API reference, so keep it open as you build.

Prerequisites

This is a hands-on tutorial with runnable code in Python, Node.js, and cURL. Before the first API call, set up the following:

A Foxit developer account for client_id / client_secret credentials. The free Developer plan includes 500 shared credits per year across PDF Services and Document Generation.
Python 3.8+ with pip and a virtual environment, or Node.js 18+ with npm. The examples use Python's requests and Node's axios plus form-data.
cURL for quick endpoint checks from the terminal.
A code editor such as VS Code with the Python extension (PyCharm, WebStorm, or Sublime Text work too).

Scaffold the workspace in one shot:

mkdir pdf-pipeline && cd pdf-pipeline
python3 -m venv .venv && source .venv/bin/activate
pip install requests
# Node alternative:
# npm init -y && npm install axios form-data
export FOXIT_CLIENT_ID="your_client_id"
export FOXIT_CLIENT_SECRET="your_client_secret"

In this block you create an isolated project directory, activate a Python virtual environment so dependencies don't leak into your system install, add the HTTP library the examples use, and export your Foxit credentials as environment variables that every script below reads from the environment rather than from hardcoded strings.

Setup and Your First API Call

Start by creating an account at account.foxit.com/site/sign-up. The free Developer plan takes about two minutes to configure and gives you immediate API access to validate a complete pipeline integration before committing to a paid tier.

Next you need a Word template. Rather than building one from scratch, download a ready-made sample, invoice_simple.docx, which already contains token placeholders. Tokens use double curly braces, and this template defines {{ companyName }}, {{ invoiceNumber }}, {{ invoiceDate \@ MM/dd/yyyy }}, and {{ totalDue \# "$#,##0.00" }}. The \@ and \# suffixes are formatting switches that tell the engine how to render dates and currency.

The first API call takes that .docx, encodes it as base64, attaches a JSON data payload, and POSTs it to the Document Generation endpoint. Encode the file first:

import base64

with open("invoice_simple.docx", "rb") as f:
    encoded = base64.b64encode(f.read()).decode("utf-8")

In this code, you open the template in binary mode, base64-encode its raw bytes, and decode the result to a UTF-8 string so it can travel inside a JSON request body. In Node.js the equivalent is fs.readFileSync("invoice_simple.docx").toString("base64"). The API doesn't care which language produced the string, only that it's valid base64 that decodes to a well-formed .docx. Send a corrupted or truncated file and you'll get an error back with no usable output.

Now POST the encoded template with a matching data payload:

curl -X POST "https://na1.fusion.foxit.com/document-generation/api/GenerateDocumentBase64" \
 -H "client_id: $FOXIT_CLIENT_ID" \
 -H "client_secret: $FOXIT_CLIENT_SECRET" \
 -H "Content-Type: application/json" \
 -d '{
   "base64FileString": "<BASE64_ENCODED_DOCX>",
   "outputFormat": "pdf",
   "documentValues": {
     "companyName": "Acme Corp",
     "invoiceNumber": "INV-1042",
     "invoiceDate": "2026-01-15",
     "totalDue": "5700"
   }
 }'

In this request, base64FileString carries the encoded template, outputFormat selects pdf (use docx to get a populated Word file back instead), and documentValues is the object whose keys map to the {{token}} names in the template. Credentials go in the headers, never in the body. Every key in documentValues corresponds to a token; tokens you omit render as an empty string, and keys that don't match any token are ignored. Values can be strings or numbers, so "totalDue": "5700" and "totalDue": 5700 both work, though sending strings keeps formatting predictable.

The response returns the generated document as a base64 string in the base64FileString field:

{
  "message": "PDF Document Generated Successfully",
  "fileExtension": "pdf",
  "base64FileString": "<BASE64_ENCODED_PDF>"
}

Decode the base64FileString value to get the raw PDF bytes, then write them to disk, push to S3, or pass them straight into the next pipeline stage. There's no separate download step and no job ID to track, since the document is in the response body.

One constraint to plan around is the 4 MB cap on the .docx payload after base64 encoding. The usual culprits when you hit that ceiling are high-resolution embedded images, embedded fonts, and OLE objects. Compress images through Word's Picture Format tools to around 150 DPI, reference fonts instead of embedding them, and drop OLE objects entirely. For templates that genuinely exceed the limit after optimization, split them into component templates and merge the outputs downstream.

Designing Templates for Dynamic, High-Volume Documents

A few token patterns cover the vast majority of document generation use cases. Master these and you can handle contracts, invoices, compliance reports, onboarding kits, and offer letters from a single template architecture. To see all of them together, download invoice_table.docx, which exercises every pattern below.

Simple field substitution is the baseline. Place {{fieldName}} anywhere in the Word document (inside a paragraph, in a table cell, in a header) and the API replaces it with the corresponding value from the JSON payload.

Formatting switches control how the engine renders dates and numbers. Append \@ MM/dd/yyyy to a date token or \# "$#,##0.00" to a numeric token, and the engine formats the output for you. In invoice_table.docx, {{ invoiceDate \@ MM/dd/yyyy }} turns 2026-01-15 into 01/15/2026, and {{ totalDue \# "$#,##0.00" }} turns 5700 into $5,700.00.

Table row iteration handles line items, variable-length lists, and repeating structures. Wrap a table row with {{TableStart:arrayName}} and {{TableEnd:arrayName}} placed in the same row, reference each object's fields with bare {{fieldName}} tokens inside that row, and pass an array of objects in the payload. The engine expands the table to one row per array element. invoice_table.docx uses this structure:

| #              | {{description}}                  | {{qty}} | {{unitPrice \# "$#,##0.00"}} | {{lineTotal \# "$#,##0.00"}} |
| {{ROW_NUMBER}} | {{TableStart:lineItems}} ...     |         |                              | ... {{TableEnd:lineItems}}   |

The {{ROW_NUMBER}} token auto-numbers each generated row, and {{=SUM(ABOVE) \# "$#,##0.00"}} in a cell below the table sums the column above it. Driving that template with this payload:

{
  "outputFormat": "pdf",
  "documentValues": {
    "companyName": "Acme Corp",
    "invoiceNumber": "INV-1042",
    "invoiceDate": "2026-01-15",
    "lineItems": [
      {
        "description": "Consulting",
        "qty": "3",
        "unitPrice": "1500",
        "lineTotal": "4500"
      },
      {
        "description": "Licensing",
        "qty": "1",
        "unitPrice": "1200",
        "lineTotal": "1200"
      }
    ],
    "totalDue": "5700"
  }
}

produces a two-row table (1 Consulting 3 $1,500.00 $4,500.00 and 2 Licensing 1 $1,200.00 $1,200.00), a computed subtotal of $5,700.00, and a Total Due of $5,700.00, all formatted by the template. A 47-item order produces 47 rows with no template changes. The lineItems array is the only part of the payload that varies between a one-item order and a fifty-item order.

The actual PDF returned by the DocGen API for the payload above. Row numbers, currency and date formatting, the expanded line-item loop, and the SUM(ABOVE) subtotal all resolved server-side from the Word template.

For variable content that should appear only sometimes, drive it from the data layer. An omitted or empty token renders as blank, and an empty array produces zero table rows, so you control which content surfaces by controlling what you put in documentValues rather than by embedding branching logic in the template.

The operational implication matters for engineering teams at scale. Template ownership can live entirely outside the application codebase, whether that's a Word file in version control, a shared drive with access controls, or a document library. Non-engineers can modify the template without triggering a deploy cycle. The application code owns JSON payload construction and the template file owns document structure, which is what keeps the system maintainable as document types multiply.

For versioning, the practical approach is environment-specific template files, such as contract-v2.docx in production and contract-v3.docx in staging for validation before promotion. When you encode the template as base64 at request time, the version is implicit in which file you read. In-flight pipeline runs hold a reference to whichever file was live when they started, so there's no race condition with a template swap mid-generation.

Post-Generation Processing: Flatten, Linearize, Compress, and Sign

Most pipelines accumulate technical debt here. Teams generate the PDF and consider the job done, then bolt on post-processing as an afterthought when compliance raises questions or storage costs spike. Build the processing stage into the architecture from the start.

The bridge between DocGen and PDF Services works like this. DocGen returns a base64 PDF string. Decode it back to bytes and upload it once to PDF Services via POST /pdf-services/api/documents/upload, a multipart form upload that returns a documentId. From that point, PDF Services jobs chain by passing one job's resultDocumentId as the next job's input documentId, with no further download and re-upload cycles between operations.

// Node.js: bridge DocGen output into PDF Services and chain jobs
const axios = require("axios");
const FormData = require("form-data");

const BASE = "https://na1.fusion.foxit.com/pdf-services/api";
const auth = {
  client_id: process.env.FOXIT_CLIENT_ID,
  client_secret: process.env.FOXIT_CLIENT_SECRET,
};

// Step 1: decode the base64 PDF from DocGen and upload it once as multipart
async function uploadDocument(base64Pdf) {
  const form = new FormData();
  form.append("file", Buffer.from(base64Pdf, "base64"), {
    filename: "document.pdf",
    contentType: "application/pdf",
  });
  const res = await axios.post(`${BASE}/documents/upload`, form, {
    headers: { ...auth, ...form.getHeaders() },
  });
  return res.data.documentId;
}

// Step 2: kick off a flatten job that returns a taskId for async polling
async function flattenDocument(documentId) {
  const res = await axios.post(
    `${BASE}/documents/modify/pdf-flatten`,
    { documentId },
    { headers: { ...auth, "Content-Type": "application/json" } },
  );
  return res.data.taskId;
}

// Step 3: start a compress job on a result document, no re-upload needed
async function compressDocument(documentId, compressionLevel) {
  const res = await axios.post(
    `${BASE}/documents/modify/pdf-compress`,
    { documentId, compressionLevel },
    { headers: { ...auth, "Content-Type": "application/json" } },
  );
  return res.data.taskId;
}

// Step 4: poll GET /tasks/:taskId until COMPLETED or FAILED
async function waitForCompletion(taskId) {
  while (true) {
    const res = await axios.get(`${BASE}/tasks/${taskId}`, { headers: auth });
    const { status, resultDocumentId } = res.data;
    if (status === "COMPLETED") return resultDocumentId; // pass to next job
    if (status === "FAILED") throw new Error(`Task ${taskId} failed`);
    await new Promise((r) => setTimeout(r, 2000)); // 2s polling interval
  }
}

// Full chain: upload -> flatten -> compress -> return final ID for eSign
async function processDocument(base64Pdf) {
  const docId = await uploadDocument(base64Pdf);
  const flatTaskId = await flattenDocument(docId);
  const flatDocId = await waitForCompletion(flatTaskId);
  const compressTaskId = await compressDocument(flatDocId, "MEDIUM");
  return await waitForCompletion(compressTaskId);
}

In this code, you take the base64 PDF that DocGen returned, decode it into a binary Buffer, and push it to the upload endpoint as a multipart file (uploading the base64 string as JSON is rejected with a 415, since the endpoint expects form data). The upload returns a documentId. You start a flatten job against that ID, poll the task endpoint every two seconds until it reports COMPLETED, then feed the returned resultDocumentId straight into a compress job without re-uploading anything. The final resultDocumentId is what you hand to the eSign stage.

Three operations cover the core post-processing needs:

Flatten (POST /documents/modify/pdf-flatten) merges form fields and annotations into static page content, baking every value in as rendered text or image with no interactive elements remaining. This is required for compliance archiving under standards like PDF/A, and for producing tamper-evident audit files. If your documents land in a regulatory audit, a flattened PDF is the format auditors expect.
Linearize (POST /documents/optimize/pdf-linearize), also called "Fast Web View," restructures the internal byte order of the PDF so the first page renders before the rest of the file downloads. For portals serving multi-page contracts or reports, this cuts perceived load time. A 40-page contract in Fast Web View starts rendering in the browser immediately rather than waiting for the full download. It's the operation most teams skip and then regret when users complain about document load times.
Compress (POST /documents/modify/pdf-compress) reduces file size without degrading visible quality and takes a compressionLevel of LOW, MEDIUM, or HIGH. For high-volume pipelines sending documents via email or storing thousands of files, the delta between an uncompressed 800 KB file and a MEDIUM-compressed 200 KB file compounds quickly at scale.

For the eSign handoff, download the final document from PDF Services with GET /pdf-services/api/documents/{documentId}/download, then submit it to the Foxit eSign API to create an envelope, assign signers, and trigger the signing workflow. Because eSign runs on a separate host (https://na1.foxitesign.foxit.com), you move the bytes across rather than passing a PDF Services document ID directly. After authenticating for an eSign access token, create a folder with the PDF attached as a base64 string and "inputType": "base64", assign signers, and send. Configure a webhook endpoint in your application and the eSign API posts events (viewed, signed, completed, declined) as they happen.

Error Handling and Monitoring in Production

Document pipelines fail in three distinct ways, and handling each correctly prevents silent data loss.

Data validation failures happen before any API call goes out. Malformed JSON, missing required token values, or structural mistakes produce generation errors that are deterministic and reproducible. Validate your data payload against a schema before sending it to the DocGen endpoint. If totalDue is null when the document needs a value, catch that in your application layer rather than discovering a blank field in the rendered output.

Template rendering errors occur when the Word template contains broken token syntax or structural inconsistencies the generation engine can't resolve, such as loop tokens split across different table rows. These typically surface during integration testing, not in production, which means they're preventable. Use the Foxit Analyze Document API (POST /document-generation/api/AnalyzeDocumentBase64) to scan a template programmatically before promoting it. It returns singleTagsString, a comma-separated list of the scalar tokens the engine detected, and doubleTagsString, the table or loop region names. Diff those against your expected token set to catch mismatches before they reach users.

Downstream chain failures are the most dangerous because they happen after a successful generation step. The PDF was created correctly, but the flatten job failed, or the eSign envelope creation returned a 400. Without explicit handling, the document disappears into limbo.

// Polling with timeout and dead-letter branching, use for every chained job
async function pollWithTimeout(taskId, timeoutMs = 30000) {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const res = await axios.get(`${BASE}/tasks/${taskId}`, { headers: auth });
    const { status, resultDocumentId, error } = res.data;
    if (status === "COMPLETED") return resultDocumentId;
    if (status === "FAILED") {
      // Log taskId, full error payload, and upstream context before re-queuing
      console.error(`Task ${taskId} FAILED:`, JSON.stringify(error));
      throw new Error(`Processing failed: ${error?.message}`);
    }
    await new Promise((r) => setTimeout(r, 2000));
  }
  // Timeout: treat as failure, don't silently drop the document
  throw new Error(`Task ${taskId} timed out after ${timeoutMs}ms`);
}

In this code, you cap the polling loop with a deadline so a stuck job can't block the pipeline forever. On COMPLETED you return the result document ID for the next stage, on FAILED you log the task ID and the full error payload before throwing, and on timeout you throw rather than returning silently, which guarantees a failed document raises a visible error instead of vanishing.

Log the task ID returned from every API call. When something fails, that ID is your audit trail into the Foxit API logs. Set timeout thresholds per stage, since a flatten job running for 60 seconds on a 10 KB file is stuck, not slow. Implement dead-letter logic for documents that fail post-generation processing, whether that means re-queuing with exponential backoff or alerting an operator. A failed post-processing step that silently drops a document is worse than a visible error.

Your Next Step: Run This End-to-End Today

The fastest way to validate the architecture is to get one call working before building the full pipeline.

Sign up at account.foxit.com/site/sign-up, where the free Developer plan takes about two minutes to configure and gives you immediate API access. Download invoice_simple.docx, base64-encode it, and call the DocGen endpoint with a JSON payload that fills companyName, invoiceNumber, invoiceDate, and totalDue. Decode the base64 response and open the PDF. That's the core loop validated in under 15 minutes, and Foxit's Postman collection in the developer portal makes it even faster to prototype before you write integration code.

From there, layer in the pipeline stages one at a time. Upload that PDF to PDF Services, run a flatten job, poll for completion, and verify the output. Then add the compress step. Then wire in the eSign handoff. Building incrementally means you know exactly where problems originate.

Foxit's developer portal has code samples in Node.js, Python, and cURL ready to copy. The free Developer plan gives you 500 shared credits per year to cover your entire exploration and POC phase.

What's the most brittle part of your current document generation setup, whether that's template management, rendering consistency, compliance archiving, or the eSign handoff? Drop your approach in the comments. The real-world variations in how teams solve this are usually where the genuinely interesting engineering decisions live.

Document Generation for Developers: Security, Compliance, and Build-vs-Buy Decisions for the Template-Plus-Data Pipeline

Lucien Chemaly — Fri, 29 May 2026 10:15:19 +0000

When a deal closes in your CRM and a contract still needs a human to open Word, paste in the account name, and adjust the pricing table, you have a document generation problem. The mechanism for solving it is well understood: a rendering engine resolves a template against a structured data payload and emits a finished file. What most guides skip is the implementation layer that determines whether the system survives an audit, scales past the first team that uses it, and stops requiring developer time after launch. That means credential handling, data residency, compliance certifications, and the build-vs-buy threshold for the rendering layer itself.

This article covers the architecture and the hard decisions. The "what is document generation" recap is intentionally short so the security, compliance, and decision-framework content has room to breathe.

Document Generation: The Core Mental Model

A document generation system does one thing: it takes a template (structural layout, fixed text, placeholders) and a data payload (field values for those placeholders), merges them in a rendering engine, and produces an output file.

Three adjacent concepts get conflated with document generation frequently enough to distinguish here. Document editing puts a human in the loop to modify content interactively. Document management handles storage, versioning, and retrieval of existing files. PDF form-fill annotates existing form fields with values without regenerating the document structure. Generation produces a net-new file on each call.

Output format is a real decision. PDF is the correct choice when the output is delivery-final, immutable, and audit-ready, such as a signed contract, a compliance report, or a customer invoice. DOCX is the right choice when the generated file feeds a downstream collaborative editing workflow, such as a first draft that legal needs to mark up before execution.

The rest of this article covers programmatic, API-driven generation at scale. If you're evaluating whether to build or buy the rendering layer, and whether your architecture can pass a SOC 2 or HIPAA review, this is the relevant frame.

The Three Components Every Document Generation System Requires

Every doc gen system at production scale requires three things: a template, a data payload, and a rendering engine. Getting the contract between them right at design time saves hours of debugging later.

Templates are .docx files authored in Microsoft Word, with {{field_name}} double-brace tags placed anywhere Word accepts text: headings, table cells, footers, text boxes, even page headers. The template is a contract with the data payload. Every tag is a required key. If {{invoiceNumber}} appears in the template and the payload omits invoiceNumber, the rendered output contains a blank where the invoice number should be. The API does not raise an error for missing keys, and absent keys render as empty strings. That behavior matters when you're designing your payload validation layer.

The data payload is a JSON object whose keys map to tag names in the template. A minimal invoice payload looks like this:

{
  "companyName": "Acme Corp",
  "invoiceNumber": "INV-001",
  "invoiceDate": "2026-01-15",
  "totalDue": 4200
}

String values drop in as-is. Numeric values render according to any format directives embedded in the tag itself, such as {{ totalDue \# "\$#,##0.00" }} for currency formatting. Null values and missing keys both render as empty strings.

The rendering engine is the service that resolves tags against the payload and emits the file. At render time, the engine performs tag substitution for scalar values, dynamic row expansion for array-backed table data, and output format encoding (Base64 for transport in JSON responses, or a binary write to disk). Its behavior on edge cases, including how it handles null values, missing keys, and malformed tags, is what you need to understand before connecting it to a production data source.

How the Foxit Document Generation API Request Model Works

The Foxit Document Generation API uses a three-field POST body. base64FileString carries the Base64-encoded .docx template. documentValues carries the JSON merge data. outputFormat is the lowercase string "pdf" or "docx". The endpoint is case-sensitive on outputFormat and returns HTTP 500 for any value outside those two strings.

The canonical endpoint for developer-tier accounts is https://na1.fusion.foxit.com/document-generation/api/GenerateDocumentBase64. Authentication is header-based: include client_id and client_secret alongside Content-Type: application/json. There is no OAuth flow, no token exchange, and no session management.

Base64 encoding is used because the API transports binary template content inside a JSON request body, where raw binary bytes would break JSON parsing. The encoding overhead adds roughly 33% to the payload size, which is why the endpoint enforces a 4 MB limit on the encoded template (approximately a 3 MB raw .docx file). Payloads that exceed this cap return HTTP 413 or a generic 500 with an opaque message. To slim an oversized template, compress images via Word's Picture Format menu, remove embedded fonts and OLE objects, and split templates that contain too many high-resolution graphics.

The synchronous execution model is a meaningful architectural choice. The rendered file arrives in the same HTTP response, eliminating the polling loop that complicates async pipelines.

sequenceDiagram
    participant App as Application
    participant API as GenerateDocumentBase64 Endpoint
    App->>API: POST with base64FileString, documentValues, outputFormat
    API->>API: Resolve tags against documentValues
    API->>API: Encode rendered file as base64
    API-->>App: 200 OK with base64FileString in response body
    App->>App: Decode base64, write output.pdf

Async polling patterns make sense when document volume is high enough to push render time past practical request timeouts, for example in overnight batch jobs processing tens of thousands of records. For on-demand generation triggered by a single user action or a webhook, synchronous delivery is simpler to implement and simpler to debug.

Dynamic tables require a specific token placement. To render an array of line items into a Word table, place {{TableStart:lineItems}} and {{TableEnd:lineItems}} in the same table row, with the field tags for each column also in that row. The engine repeats the row for each element in the lineItems array. You can also include {{ROW_NUMBER}} in the row to get an auto-incrementing index. Placing the start and end tokens in different table rows produces a broken render with no error message, which is one of the more opaque failure modes in the system.

The Analyze Document API is a utility endpoint worth knowing about when evaluating any doc gen service. Post a .docx file to it and it returns all embedded tag names in the template. This lets you programmatically validate that a template matches a payload schema before calling the generation endpoint, and auto-build the documentValues structure from a template file when the template changes.

Integration Patterns for Production Document Generation Workflows

The most common trigger pattern in CRM-connected workflows goes like this: a deal moves to Closed Won in Salesforce, a webhook fires to your application, your application queries Salesforce for the deal fields, your application posts to the doc gen API, the rendered PDF contract comes back synchronously, and your application attaches the file to the CRM record or sends it to the signatory. Because the API is a standard REST endpoint, integrating with HubSpot, Salesforce, or SAP requires no proprietary connector, just an authenticated HTTP POST.

For event-driven batch jobs, iterate over a dataset of N records and fire one POST per record. The key considerations are rate limiting and retry logic. If the downstream data source or the doc gen service has a request ceiling, a simple backoff-and-retry pattern handles transient failures without losing records. Log the request metadata (template version, record ID, timestamp) and the response status. Omit payload contents from logs when the payload contains regulated data.

When a required tag has no corresponding key in documentValues, the API renders a blank and moves on. The defensive pattern is to run payload validation against the tag list returned by the Analyze Document API before each call. For workflows where partial data is acceptable, build a fallback that fills missing keys with empty strings explicitly rather than relying on the API's implicit behavior. That delta matters during an audit when you need to explain why a generated compliance report had blank fields.

Security and Compliance for Document Generation Pipelines

client_id and client_secret travel as HTTP request headers, which means they're visible in any intermediary that can inspect headers in transit. Store them in environment variables or a secrets manager (AWS Secrets Manager, HashiCorp Vault, or a CI/CD-native secrets store). They should never appear in source code, version control, or log output. Your application code should read from os.environ["CLIENT_ID"] rather than hardcoding the string value.

TLS at the API boundary encrypts the payload in transit, but your application is responsible for what happens to the document after the response arrives. If you're writing the rendered PDF to disk, a message queue, or cloud storage, that persistence layer needs its own encryption at rest. An unencrypted file sitting in an Amazon S3 bucket with overly permissive ACLs falls outside what the API provider's TLS covers.

SOC 2 Type II, GDPR, and HIPAA each have specific implications for doc gen pipelines that go beyond a logo on a vendor's compliance page. SOC 2 Type II requires an auditable trail of access controls and data handling over time, so you'll need to log which user or service account triggered each generation event and what template was used. GDPR treats personally identifiable information in generated documents as regulated data, which means data subject rights (access, deletion, correction) extend to any stored generated files in addition to the source database records. HIPAA adds the requirement that protected health information (PHI) in generated documents be handled under a signed Business Associate Agreement (BAA) with every service that processes or stores that data. Foxit's API platform carries SOC 2, GDPR, and HIPAA compliance posture, so the BAA question is addressable at the vendor level, but the application layer between your data source and the API remains your responsibility.

Template files are themselves a security surface. Avoid embedding default field values that contain PII directly in the template file, because .docx files land in version control, get emailed for review, and end up in shared drives. The template should contain the structural layout and formatting only, with PII traveling exclusively in the documentValues payload at generation time, ephemeral in the request and response.

Most managed doc gen providers don't persist the rendered document on their infrastructure after returning it in the response body, but verify this contractually before connecting regulated data. Log the request hash and response status. Document contents belong only in the storage system you control and have audited.

Build vs. Buy: Picking the Right Document Generation Rendering Approach

The DIY path uses open-source libraries. python-docxtpl renders Word templates in Python using Jinja2 syntax, covering scalar substitution and table loops at no licensing cost. jsPDF lets you construct PDFs in Node.js from scratch via code. Both give you complete control over rendering logic, and neither comes with a licensing fee. The cost is that your team owns maintenance, scaling infrastructure, and all compliance certification work. When your open-source rendering library has a memory leak under high concurrency, or when your auditor asks for your SOC 2 report, you answer those questions directly.

A managed REST API trades infrastructure ownership for faster integration, predictable credit-based pricing, and inherited compliance certifications. The break-even point shifts depending on three variables: team size, document volume, and whether the use case requires certified compliance. At low volume (fewer than 500 documents per month) with no regulated data, the open-source path is often the right call. At higher volume, or when a compliance review is on the roadmap, the time cost of building and certifying your own rendering infrastructure typically exceeds the subscription cost of a managed service by a meaningful margin.

To work out which path makes sense for your situation, answer these four questions:

How many documents does the system need to generate per month, and is that number growing?
Does the content include regulated data (PII, PHI, financial records) that triggers a compliance framework?
Does your team have in-house PDF rendering expertise, or would you be learning while building?
How often does the template change, and who owns that change process?

If document generation is a core differentiating feature of your product, investing in a custom rendering layer may pay off over time. If it's a workflow utility (such as generating invoices, contracts, or onboarding letters from existing system data), a managed API ships faster and costs less in total at moderate volume. The key signal is whether the rendering logic itself creates competitive value or whether it's plumbing.

Prerequisites

You'll need Python 3.8+ and pip for the quickstart, with venv recommended for isolation. Install the requests library for HTTP calls. VS Code with the Python extension works well as an editor, though PyCharm or Sublime Text work equally well. You'll also need a free Foxit developer account.

Set up the workspace and load your credentials into the environment:

mkdir foxit-docgen-quickstart && cd foxit-docgen-quickstart
python3 -m venv .venv && source .venv/bin/activate
pip install requests
export BASE_URL="https://na1.fusion.foxit.com"
export CLIENT_ID="your_client_id"
export CLIENT_SECRET="your_client_secret"

Quickstart: Generate Your First Document via the API

Step 1. Activate a free developer plan at account.foxit.com/site/sign-up. You get 500 annual credits and no credit card is required. Retrieve CLIENT_ID and CLIENT_SECRET from the API Keys section of the developer dashboard, then load them into your environment using the block above.

Step 2. Download the sample invoice template from the foxit-demo-templates repository. The file contains {{ companyName }}, {{ invoiceNumber }}, {{ invoiceDate \@ MM/dd/yyyy }}, and {{ totalDue \# "\$#,##0.00" }} tokens, already validated against the live API.

Step 3. The script reads credentials from os.environ, Base64-encodes invoice_simple.docx, POSTs the three-field JSON body to https://na1.fusion.foxit.com/document-generation/api/GenerateDocumentBase64, decodes the base64FileString field in the response, and writes the bytes to output.pdf:

import base64
import json
import os
import requests

base_url = os.environ["BASE_URL"]
client_id = os.environ["CLIENT_ID"]
client_secret = os.environ["CLIENT_SECRET"]

with open("invoice_simple.docx", "rb") as f:
    template_b64 = base64.b64encode(f.read()).decode("utf-8")

payload = {
    "base64FileString": template_b64,
    "documentValues": {
        "companyName": "Acme Corp",
        "invoiceNumber": "INV-001",
        "invoiceDate": "2026-01-15",
        "totalDue": 4200
    },
    "outputFormat": "pdf"
}

headers = {
    "client_id": client_id,
    "client_secret": client_secret,
    "Content-Type": "application/json"
}

response = requests.post(
    f"{base_url}/document-generation/api/GenerateDocumentBase64",
    headers=headers,
    data=json.dumps(payload)
)
response.raise_for_status()

result = response.json()
output_bytes = base64.b64decode(result["base64FileString"])

with open("output.pdf", "wb") as f:
    f.write(output_bytes)

print("Rendered document written to output.pdf")

output.pdf is a rendered, branded invoice generated from structured data in a single synchronous HTTP call.

What integration pattern is your team using to trigger document generation: synchronous on-demand, event-driven, or batch?

Common Mistakes and Troubleshooting

Word's autocorrect will silently replace straight quotes inside tags with smart (curly) quotes in some locales, which breaks tag parsing entirely. The risk shows up most often in format directives such as {{ totalDue \# "$#,##0.00" }}, where the "..." around the picture string is what gets converted. If your tags aren't resolving, paste them from a plain-text editor rather than typing them directly in Word, or disable autocorrect for the template file.

Tag names are case-sensitive throughout the system. {{ companyName }} and {{ CompanyName }} are different tags. Cross-check every placeholder in the template against the JSON payload keys before your first test call.

Missing payload fields render silently as empty strings. Validate the full payload against the tag list from the Analyze Document API before each call in production, especially when templates change and new tags get added without a corresponding update to the payload-building code.

Loop tokens must sit in the same Word table row. Placing {{TableStart:lineItems}} in row 1 and {{TableEnd:lineItems}} in row 2 produces a broken render with no error. The entire row that contains both tokens becomes the repeating unit.

The base64.b64encode() function in Python returns a bytes object. Forgetting the .decode("utf-8") call means you'll pass a bytes object into json.dumps(), which raises a TypeError: Object of type bytes is not JSON serializable. The error message points at the serializer rather than the encoding step, which makes the root cause easy to miss.

When a template hits the 4 MB encoded size cap, the API returns HTTP 413 or a 500 with a vague message. Slimming the template is the fix. Retrying with the same payload produces the same error. Compress images via Word's Picture Format compress tool, remove embedded fonts, and drop any OLE objects you don't need in the generated output.

Conclusion

Document generation looks like a templating problem until you put it in front of an auditor. The rendering pipeline itself is the easy part, a template plus a structured payload merged by an engine that returns a finished file. What separates a working prototype from a system that holds up in production is the layer around the engine, where credential handling, data residency, SOC 2 and HIPAA coverage, and the build-vs-buy threshold are decided.

The build-vs-buy decision compounds over time. An in-house pipeline on top of python-docx or WeasyPrint is defensible when the output format is fixed, the templates are stable, and the team has long-term capacity to own the rendering layer. Once any of those assumptions slips, the compliance surface, the template maintenance burden, and the cross-format requirements pull engineering attention away from the product itself. Shifting the rendering layer to a managed API with SOC 2 Type II, GDPR, and HIPAA coverage already in place removes a class of work that does not differentiate your product, in exchange for a vendor dependency that is easier to manage than a homegrown engine.

The Python quickstart above is the smallest possible version of the production pattern, with credentials read from the environment, a synchronous request to GenerateDocumentBase64, and a base64-decoded PDF written to disk. From there the path forward is well-trodden, by adding template validation through the Analyze Document API, layering retries and observability around the call, and expanding the template library as new document types come online. The architecture and the hard decisions are the same whether you generate ten documents a day or ten thousand. Getting them right early is what keeps the system out of the audit findings later.

To test the three-field request model against a live endpoint today, activate a free Foxit developer account (no credit card and no sales call required) and run the Postman collection. Sign up at account.foxit.com/site/sign-up.

LINKEDIN POSTS

LinkedIn Post 1

Most teams treat document generation as a template problem. The real problem is the implementation layer that sits around the template.

The rendering pipeline itself is well understood: a template plus a structured data payload produces a finished file. PDF for audit-ready delivery, DOCX for collaborative editing workflows. That part takes an afternoon to prototype.

What takes months to get right:

Credential handling that doesn't leak API keys into logs or environment variables
Data residency controls for documents that carry PII or contract terms
SOC 2 and HIPAA compliance at the rendering layer, not just at the application layer
A build-vs-buy threshold that accounts for long-term maintenance, not just first-week velocity

The teams that skip this layer ship a working proof of concept, then spend the next two quarters patching it before an audit.

I wrote a detailed guide covering the architecture and the hard decisions, including a Python quickstart against the Foxit Document Generation API. Link in the comments.

LinkedIn Post 2

The build-vs-buy decision for document generation has one real variable: who maintains the rendering engine when requirements change.

Building your own pipeline on top of a library like python-docx or WeasyPrint is the right call when your output format is fixed, your templates are stable, and you have engineering capacity to own it long-term. Most teams don't have all three.

The hidden costs of building in-house:

HIPAA-compliant rendering requires data processing agreements and infrastructure controls your team has to configure and certify
SOC 2 coverage for the rendering layer means your internal build is in scope for your next audit
Template maintenance compounds as output types multiply across contracts, invoices, and compliance reports

Using a managed API like Foxit's shifts the compliance surface area and the maintenance burden off your team. The trade-off is vendor dependency, which is worth the cost once you're past the first two or three document types.

Full guide with the architecture breakdown and a working Python quickstart in the comments.

LinkedIn Post 3

The most common bug in a production document generation pipeline is silent.

A required field is missing from the payload. The API returns 200. The rendered PDF ships with a blank where the customer name should be. Nobody catches it until the customer does, or worse, until an auditor does.

This happens because the template-to-data contract is implicit. A Word template declares placeholders with {{ field_name }} tags, but a .docx file is not a schema. The rendering engine merges what it can match and treats missing keys as empty strings by design. That is the right default for a generic engine and the wrong default for a regulated workflow where a blank field is a real problem.

The pattern that closes the gap:

Use the Analyze Document API (or your provider's equivalent) to enumerate every tag in the template before each call
Validate the payload against that tag list at build time, not at render time
Treat a missing key as an explicit error in your application layer, not a downstream PDF problem
Log the template version and the payload schema together so audit reconstruction has both halves

Most managed doc gen APIs expose a template introspection endpoint for exactly this reason. Foxit ships one. Use it.

The full guide covers this pattern plus the rest of the security, compliance, and build-vs-buy decisions. Link in the comments.

Should You Vibe Code Your SaaS Starter or Just Buy One?

Lucien Chemaly — Fri, 29 May 2026 06:39:09 +0000

It's 2026 and AI coding tools have made everyone feel like a 10x engineer. Cursor writes your components. Claude Code refactors your whole codebase between sips of coffee. v0 spits out landing pages from a prompt. Bolt and Lovable promise you a "full SaaS in one shot."

So the thought creeps in: why would I pay $69 for a Next.js SaaS starter kit when I can vibe code one myself in a weekend?

This article is the answer to that question, with actual numbers. I'm going to walk through what it really takes to build a production-ready SaaS starter in 2026 with AI tools, how much it costs in subscriptions and time, and what you get for $69–$119 if you just buy one. Then you can decide for yourself.

Spoiler: the math is not even close.

What "production-ready" actually means

Before the math, let's pin down what we're building. A SaaS starter isn't a landing page. It's the entire foundation a paid product sits on. Bolt and Lovable can scaffold a frontend in a prompt; they cannot ship you the following list.

Here's what a real Next.js SaaS starter includes:

Authentication. Email/password, password reset, email verification, session management. Probably social OAuth (Google, GitHub, etc.). Probably 2FA. Definitely RBAC (owner, admin, member roles).
Payments. Stripe and/or LemonSqueezy. Subscriptions and one-time purchases. Customer portal. Webhook handling with signature verification, idempotency, and retry logic. Two-way product sync. Guest checkout. Tax. Refunds.
Database. Schema, migrations, seed data, RLS or equivalent permission layer, multi-tenancy if you need it.
Admin panel. User management, billing oversight, support tools, feature flags, maintenance mode.
Content layer. A CMS or page builder so a non-developer can edit marketing pages without a deploy. (Most kits ship an MDX folder and pretend this is a CMS. It isn't.)
Email. Transactional (welcome, password reset, receipt), templated, with a real provider (Resend, Postmark, SES).
Observability. Error tracking (Sentry), analytics, logging.
Security. Rate limiting, CSRF, secure headers, input validation everywhere, secret management.
Testing. Unit tests, E2E tests, CI pipeline.
DX. TypeScript strict mode, ESLint, Prettier, Husky, env validation, type-safe API.
Deploy. Vercel/Render/Fly/Cloudflare config, env vars, preview deployments, production runbook.

This is the floor. Skip any of it and you're shipping a hobby project, not a SaaS.

The vibe coding budget: what AI actually costs in 2026

Let's price the toolchain. You're not vibe coding with one tool — you're stitching several together.

Tool	Monthly Cost	What it's for
Cursor Pro	$20	Day-to-day code editor
Claude Max (5x or 20x)	$100–$200	The model that actually does the heavy lifting on long contexts
ChatGPT Plus	$20	Second opinion, image gen, faster turnaround on small stuff
v0 by Vercel (Premium)	$20	UI scaffolding
GitHub Copilot Pro	$10	If you want completion in your IDE too
Realistic total	$170–$270/mo

You can scrape by on $20–$40/mo with just Cursor and Claude Pro, but if you're seriously trying to build a production codebase with AI doing most of the writing, you'll burn through Pro-tier limits in a week. Anyone who's actually shipped a real project with AI in 2026 knows the $100+/month tier is where the work happens.

If the build takes you three months (we'll get to why that's optimistic in a second), you're looking at $500–$800 just in subscriptions.

The time budget: how long this actually takes

Here's the part most "vibe code your SaaS" tweets quietly skip. AI is fast at scaffolding. AI is medium-speed at debugging. AI is slow at the parts of a SaaS that matter most.

Let me break it down by component, with realistic ranges for a developer using current AI tools (2026), assuming 8-hour workdays:

Component	Hours (with AI)	Hours (without AI)
Auth with RBAC, 2FA, OAuth	20–40	60–100
Stripe + webhook reliability	30–60	80–120
LemonSqueezy as second provider	15–25	40–60
Database schema, migrations, RLS	15–25	40–60
Admin panel	30–50	80–120
CMS / page builder	60–150	200–400
Email + templates + provider wiring	10–20	30–50
Analytics dashboard	15–40	40–80
Observability (Sentry, logging)	5–10	15–25
Testing (unit + E2E)	20–40	60–100
Security pass (rate limiting, headers, validation)	10–20	30–50
Deploy, CI, env config	10–20	30–50
Landing pages, marketing, docs	20–40	50–80
Polish, edge cases, bug hunting	40–80	80–160
Total	300–620 hours	835–1,455 hours

AI saves you roughly half the work. That's real. But half of "a lot" is still a lot.

At a conservative $50/hour for a senior developer (and if you're cheaper than that, you're using time you could spend on the actual product), that's $15,000–$31,000 of your own time.

At $100/hour: $30,000–$62,000.

Where AI quietly costs you money

The hours estimate above assumes everything works. It usually doesn't. Here's where AI confidently produces code that almost works and then bites you in production.

Stripe webhooks. AI will write a webhook handler that looks great. Then a customer chargebacks, the event arrives out of order, your idempotency key is wrong, you double-issue a refund, Stripe disputes, you spend a Saturday on the phone with support. Stripe webhooks are where junior developers — and apparently most LLMs — discover the meaning of "distributed systems."

Session management. AI will give you a working JWT auth flow on the happy path. Then a user clears cookies on one device, the refresh token expires on another, and they hit an infinite redirect loop. You will debug this for two days.

Row-level security. AI is genuinely bad at RLS policies. Either it generates policies that don't actually enforce anything (so any logged-in user can read every other user's data), or it generates policies so restrictive that no one can read anything. There is no middle ground in the default output.

The CMS. This is the killer. Building a real CMS — drag-and-drop sections, inline editing, media library, draft/publish, image optimization, slug routing, SEO fields — is the kind of multi-week subsystem that AI scaffolds in a day and then can't finish in three months. It's a UX problem, not a code generation problem.

Email deliverability. AI writes the SMTP code. It doesn't tell you about SPF, DKIM, DMARC, warmup periods, or why your password reset emails go to spam for two weeks.

Edge cases you don't know exist. What happens if a webhook fires before a user's account row commits? What if a Stripe customer object exists but the local user row doesn't? What if two browser tabs both try to refresh a token at the same time? AI doesn't ask these questions. You only learn the questions after you ship and break.

Each of these gotchas costs you a day to a week. There are dozens of them. They're the difference between "I built a SaaS in a weekend" Twitter content and an actual production system.

What buying gets you for $69

For comparison, here's what a current-generation Next.js SaaS starter ships with on day one:

Next.js (latest), TypeScript strict mode
Auth with RBAC, password reset, email verification
Stripe and LemonSqueezy (toggle via env var)
Webhook handlers with signature verification, idempotency, retry
Customer portal with subscription and billing management
Admin panel with user, billing, and content management
A real CMS with 20+ section templates and a media library (if you pick the right kit — see the previous section on this)
AI chat widget with intent detection and lead capture
Real-time analytics with UTM attribution
Email integration (Resend, SES, etc.)
52+ unit tests, Playwright E2E tests
15 database migrations
15+ pre-built themes
Coming Soon and Maintenance modes
A CLAUDE.md so your AI tools actually understand the codebase

Price: $69–$119, one time.

The time-to-value is also different. With a ready-made kit, you clone the repo, fill in your env vars, and have a working SaaS in an afternoon. With a vibe-coded build, you have an afternoon of work that takes you to maybe 5% of the feature list above.

The honest math

Let me put it side by side.

	Vibe code with AI	Buy a starter kit
Cash outlay	$500–$800 (subscriptions over 3 months)	$69–$119 (one-time)
Your time	300–620 hours	5–20 hours setup
Cost of your time @ $50/hr	$15,000–$31,000	$250–$1,000
Time to working SaaS	3–6 months	1 afternoon
Risk of production bugs	High	Low (battle-tested code)
Maintenance	You, forever	Kit updates from maintainer
Learning value	High	Low

If your time is worth literally nothing — you're a student, you're between jobs, you're treating this as your free education — then vibe coding makes sense.

For anyone else, the comparison isn't $69 vs $500 in AI subscriptions. It's $69 vs three to six months of your life.

When you should vibe code it anyway

I'm going to push back on my own argument now, because there are real cases where building it yourself is the right call.

You're learning. If the goal is to understand how a SaaS works end-to-end, building it yourself with AI as your tutor is genuinely valuable. You'll come out the other side a better developer. The "wasted" time is the point.

Your stack is exotic. If you want to build on Bun + Hono + LibSQL + Better Auth + Polar + Cloudflare Workers, no starter kit serves you. You're going to build a lot of this yourself anyway.

You have specific architectural requirements. Multi-tenant with strict data isolation? On-prem deployment? Air-gapped enterprise? Most starter kits assume single-tenant SaaS on a cloud provider. Roll your own.

You're a senior engineer who actually QAs AI output. If you can spot when AI generates a subtly broken Stripe webhook and fix it in 10 minutes, the time penalty is much smaller. AI as a productivity multiplier for someone who already knows the answers is genuinely transformative. AI as a substitute for senior judgment is a trap.

You enjoy it. This is a real reason. If you'd rather spend a Saturday building auth than reading a kit's documentation, do it. Just don't pretend it's the economically rational choice.

When you should just buy

For everyone else — solo founders, indie hackers, teams who want to be selling product not building plumbing — the answer is obvious. Buy a starter kit.

The starter kit market in 2026 is more competitive than it's ever been. $69 buys you a codebase that two years ago would have been a $50,000 contract job. The differentiator now is which kit fits your needs, not whether to build it yourself.

If you want the most feature-complete kit on the market right now — auth, payments (Stripe + LemonSqueezy), admin panel, a real drag-and-drop CMS with 20+ section templates, AI chat widget, real-time analytics, the whole package — RapidLaunch ships all of it for $69–$119, one-time. That's less than a single month of Claude Max plus Cursor. And you'd still have to write the code.

The actual question

The vibe coding question is really a question about what you want to be doing.

If you want to be building a SaaS product — the thing that solves a customer problem, the thing you can sell — buying a starter is the only sane move. Your time is better spent on what makes your product different, not on rebuilding auth for the thousandth time.

If you want to be building a codebase for the experience of building it, vibe code away. AI makes this more fun than it's ever been.

Just be honest with yourself about which one you're doing.

Skip the build, ship the product →

The Best Next.js SaaS Starter Kits with a Built-in CMS (2026)

Lucien Chemaly — Mon, 18 May 2026 18:35:21 +0000

It's month two of your SaaS. Your co-founder pings you on Slack: "Can we change the hero headline? I think it's confusing." You open the repo, edit a string, push, wait for Vercel, redeploy. Five minutes for a typo.

Three weeks in, you've done this fifteen times.

This is the dirty secret of Next.js SaaS boilerplates. Almost all of them ship "a CMS" that turns out to be a folder of MDX files. Great for a developer who loves Git. Catastrophic for anyone else on the team — a non-technical co-founder, a marketing hire, a freelance copywriter — who needs to update content without going through a pull request.

Once you actually need a content workflow, you have three options:

Integrate a headless CMS as a separate service (Contentful, Sanity, Storyblok). Adds infrastructure, a recurring bill, another vendor.
Build one yourself. Weeks of work. Custom admin UI, role-based permissions, image uploads, draft/publish states, preview, version history. You will get this wrong the first time.
Pick a starter kit where the CMS is already built in. Cheapest, fastest, and the only option a sane solo founder should consider in 2026.

This article is about option three. I looked at the Next.js SaaS starter kit market and asked one question: who can actually run the marketing site without touching code?

Most kits don't make the cut. The ones that do break into three tiers, and the gap between tier 1 and tier 3 is enormous.

What counts as a "real" CMS in a starter kit

Before the ranking, here are the criteria. There are three tiers of CMS capability in this market, and the difference between them is what a non-developer can actually do on day one.

Tier 1 — Visual page builder / drag-and-drop CMS. A non-developer can build, edit, and publish marketing pages from an admin UI. Sections are pre-built components, content is editable inline, no Git involved. This is what most people picture when they say "CMS."

Tier 2 — Integrated headless CMS. A real CMS UI (typically Sanity Studio or similar) is wired into the kit. A non-developer can edit structured content (blog posts, testimonials, FAQs), but page layout is still code. You're not paying for the CMS as a separate SaaS — it ships with the kit.

Tier 3 — MDX blog. Markdown files in a /content folder. Useful for technical blogs, useless for anyone who doesn't use Git. Some kits dress this up with extra content types (changelog, roadmap), but the workflow stays dev-only.

Kits that ship none of the above don't make the list. I'll cover those briefly at the end for completeness.

A real-world test: changing the hero headline

Before the ranking, here's the test I keep coming back to. Imagine your co-founder, who doesn't code, wants to A/B test two hero headlines. What happens in each tier?

Tier 1 (visual builder): Log into the admin panel, click the hero section, type the new headline, save. Live in 30 seconds.
Tier 2 (headless CMS): Log into the CMS dashboard, find the "Homepage" document, edit the heroTitle field, publish. Live in a minute or two — but only if the developer set up that field as editable content, which is a one-time piece of work that may or may not be done.
Tier 3 (MDX blog): Slack the developer. Wait. The developer edits a .tsx file, commits, pushes, waits for the deploy. The headline is hardcoded, so they may have to refactor it before they can change it. Live in 20 minutes to 2 hours.

That's the difference between a CMS and a Git workflow with extra steps. Keep this scenario in mind as you read.

Here are the six kits with a real content layer, ranked by depth.

1. RapidLaunch — Tier 1 (Visual Page Builder)

Price: $69 (Starter) / $119 (Pro/Unlimited) — one-time
URL: rapidlaun.ch
CMS type: Drag-and-drop visual page builder

RapidLaunch is the only kit on this list with a full visual page builder out of the box. You get 25+ templates, 35+ customizable components, 20+ section templates, a visual navigation editor, a footer editor, and a media library. There's also an AI template generator that scaffolds a complete site layout from a business description.

What a non-developer can do on day one:

Build a landing page from pre-made sections (hero, pricing, FAQ, testimonials, feature grid, etc.) by dragging them into place
Edit copy, swap images, change CTAs without touching code
Edit the main navigation and footer through dedicated editors
Upload and manage images through the media library
Toggle Coming Soon mode or Maintenance mode with one click

This is the kind of workflow most teams don't get until they pay for Webflow ($30+/month) or stand up a headless CMS as a separate service. RapidLaunch ships it as part of the kit.

The rest of the stack (carried over from the wider comparison): Next.js 16 with App Router, TypeScript in strict mode, Supabase for database/auth/storage, Stripe and LemonSqueezy (choose via env var), Tailwind CSS + DaisyUI with 15+ theme presets, TipTap rich text editor, TanStack Query, Vitest + Playwright. Authentication includes Owner + Admin roles (RBAC).

Trade-offs: Supabase is the only database option. Auth is email/password only out of the box — Supabase supports social OAuth, but you'd add it yourself. The project is newer than ShipFast or Makerkit, so the community is smaller (though growing).

Verdict: The only kit on this list where a non-developer can run the marketing site from day one. If editing pages without a deploy is a requirement, this is the pick.

2. Indie Starter — Tier 2 (Sanity CMS Integration)

Price: $69 (Tier 1) / $199 (Tier 2) / $299 (Tier 3) — one-time, unlimited projects
URL: indie-starter.dev
CMS type: Integrated Sanity Studio

Indie Starter wires Sanity CMS into the kit so you get a real headless CMS UI without setting it up yourself. Most kits with a "blog" mean MDX files. Indie Starter means a hosted CMS dashboard where you can model content types, edit posts in a rich editor, schedule publishing, and manage media — the standard Sanity workflow.

What a non-developer can do on day one:

Edit blog posts, articles, and any custom content types in Sanity Studio
Upload and manage images
Preview content before publishing
Schedule posts

What they can't do: edit landing-page layout. Marketing pages are still code. The CMS handles structured content, not visual page composition.

The rest of the stack: Next.js (latest), TypeScript, Supabase (PostgreSQL), magic links + Google/GitHub OAuth, Stripe with webhooks, Tailwind CSS + Shadcn/ui, Resend, Umami + Google Analytics, Zod. SEO infrastructure (sitemaps, robots.txt, Schema.org) is built in.

Trade-offs: Sanity is a separate service. The integration is free, but Sanity has its own free-tier limits (3 users, 10K documents, 5GB assets) — if you outgrow them, that's a separate bill. Some features are tier-locked, so check what's in the $69 tier before committing. Supabase is the only database option. Limited auth compared to bigger kits.

Verdict: The second-best CMS story in this market, and at $69 the cheapest path to a real headless CMS workflow. Best for content-heavy products (blogs, knowledge bases, documentation) where structured content matters more than landing-page flexibility.

3. Nextbase — Tier 3+ (MDX Blog + Content Features)

Price: $99 (Essential) / $299 (Pro) / $399 (Ultimate) — one-time, lifetime access
URL: usenextbase.com
CMS type: MDX blog + roadmap, changelog, user feedback (Pro tier and up)

Nextbase ships an MDX blog like everyone else in tier 3, but the Pro tier ($299) adds content features that most starter kits don't: a user feedback collection system, a public roadmap, and a changelog. None of these are a CMS in the strict sense, but they're content features you'd otherwise build yourself or pay separate tools for (Canny, Featurebase, etc.).

What a non-developer can do on day one:

Read user feedback and roadmap submissions in the admin panel
Publish changelog entries (depending on implementation)
Not much beyond that — blog content still lives in MDX

The rest of the stack: Next.js 15+, TypeScript, Supabase, Stripe, Tailwind CSS + Shadcn, Jest + Playwright, Sentry, PostHog + Google Analytics, OpenAI GPT-4. The monitoring stack (Sentry + PostHog) is a real differentiator — you start with observability instead of bolting it on later.

Trade-offs: The blog is still MDX. Features are tier-locked, so the content extras only show up at $299 Pro and above. Supabase only. Smaller community than ShipFast or Makerkit.

Verdict: Worth considering if you want product-content features (feedback, roadmap, changelog) bundled in. Not a CMS replacement, but the closest thing to one in the tier 3 group.

4. ShipFast — Tier 3 (MDX Blog)

Price: $199 (Starter) / $249 (All-in) / $299 (Bundle) — one-time
URL: shipfa.st
CMS type: MDX blog

ShipFast is the most popular Next.js boilerplate by community size, but the CMS story is minimal: an MDX blog. That's it. No admin UI for content, no headless CMS integration, no page builder. ShipFast is built around the philosophy of shipping fast — content management is something you add later if you need it.

The rest of the stack: Next.js 15, TypeScript or JavaScript, MongoDB or Supabase, Google OAuth + magic links, Stripe + LemonSqueezy, Tailwind CSS, Mailgun or Resend. The 8,000+ Discord and shipping culture are the real product — the codebase itself is lighter than most competitors at the same price.

Trade-offs: Beyond the lack of CMS, there's no admin dashboard beyond basic user management, no analytics, no AI features. If your SaaS grows past MVP, you'll build a lot on top of what ShipFast ships.

Verdict: Best for founders who want to ship an MVP in a week and don't care about a CMS workflow until later. If you do care about CMS, look elsewhere.

5. LaunchFast — Tier 3 (MDX Blog)

Price: $99 (single framework) / $149 (Astro + Next.js + SvelteKit bundle) — one-time
URL: launchfa.st
CMS type: MDX blog

LaunchFast is the "bring your own stack" kit — it supports 5+ database providers, multiple email services, several storage backends, and deploys to half a dozen targets. The trade-off is that the kit itself is less opinionated, which extends to content: you get an MDX blog and the assumption that you'll wire up whatever CMS you want on top.

The rest of the stack: Next.js (also Astro and SvelteKit), TypeScript, MongoDB/Firebase/PostgreSQL/Redis/SQLite, flexible auth, Stripe + LemonSqueezy, Resend/Postmark/SendGrid/Mailgun/AutoSend, S3/R2/Firebase/Supabase Storage.

Trade-offs: Maximum flexibility, but more decisions and more wiring. If you want a CMS, you're integrating one yourself.

Verdict: Good if you already know you want a specific CMS (Payload, Strapi, Sanity, Directus) and want a kit that won't fight you when you add it. Not good if you want a CMS to be solved for you.

6. Shipped.club — Tier 3 (MDX Blog + Special Pages)

Price: $149 — one-time, lifetime access
URL: shipped.club
CMS type: MDX blog + waitlist / pre-order / affiliate pages

Shipped.club ships an MDX blog plus pre-built pages most kits don't include: a waitlist page, a pre-order page, and an affiliate program page. These aren't CMS-managed (they're code), but they're content surfaces that ship working out of the box.

The rest of the stack: Next.js 14, TypeScript, Supabase, NextAuth + Supabase Auth, LemonSqueezy (no Stripe), ChakraUI + Tailwind, MailChimp + Loops. PPP pricing is a nice touch.

Trade-offs: Stuck on Next.js 14. LemonSqueezy is the only payment option. Supabase only. Less documentation than the bigger kits.

Verdict: Worth considering if the bundled pages (waitlist, pre-order, affiliate) save you time and an MDX blog is enough on the content side.

Kits without any CMS at all

For honesty: four kits in the broader Next.js SaaS market ship with no CMS layer of any kind. Worth mentioning so this list doesn't look cherry-picked.

Supastarter ($349+): excellent on payments (5 providers), team management, and multi-framework support (Next.js / Nuxt / SvelteKit), but blog and docs only — no CMS.
Makerkit ($299+): strong on multi-tenant B2B with row-level security and the most complete auth on the market, but no CMS.
Nextless.js ($699+): AWS-native with serverless and React Native support, but no CMS.
Vercel SaaS Starter (free): minimal by design — auth, Stripe, Drizzle. You'd add a CMS yourself.

These are good kits for what they do. They just don't compete on content management.

CMS-Focused Comparison Table

Kit	Price	CMS Type	Non-Dev Editing	Blog	Visual Builder	Media Library
RapidLaunch	$69	Drag-and-drop builder	Yes	Via CMS	Yes (20+ sections)	Yes
Indie Starter	$69	Sanity CMS	Yes (Sanity Studio)	Sanity	No	Yes (Sanity)
Nextbase	$99 / $299 Pro	MDX + feedback/roadmap	Partial (admin only)	MDX (Pro)	No	No
ShipFast	$199	MDX	No	Yes	No	No
LaunchFast	$99	MDX	No	Yes	No	No
Shipped.club	$149	MDX + special pages	No	Yes	No	No

How to Choose

Choose RapidLaunch if you need a non-developer to own the marketing site, or you don't want to redeploy every time a headline changes. The drag-and-drop builder is the only one of its kind in this market, and at $69 one-time it undercuts two months of a Webflow CMS subscription.

Choose Indie Starter if you want a real headless CMS workflow (Sanity Studio) at the lowest possible entry price ($69). Best for content-heavy products where structured content matters more than visual page composition.

Choose Nextbase Pro if you want product-content features (user feedback, roadmap, changelog) bundled with your starter, and you're okay with MDX for the blog itself.

Choose ShipFast, LaunchFast, or Shipped.club if an MDX blog is genuinely enough for now and you'll handle content management yourself later. These are good kits — just don't pick them expecting a CMS workflow.

Final Thoughts

The CMS gap in the Next.js SaaS starter market is real. Most kits hand you authentication, payments, and a landing page, then leave content management as an exercise for the reader. For solo developers building their first product, that's often fine. For anyone with a non-technical co-founder, a marketing function, or a growth-stage product where copy changes weekly, it's a problem you'll hit by month two.

If you want a CMS workflow without paying extra for one or building it yourself, the practical choice today is RapidLaunch for a full visual page builder, or Indie Starter for an integrated Sanity workflow at the lowest price. Everything else in this market punts on the content layer.

If I were starting a new SaaS today and knew I'd be editing the marketing site regularly, I'd pick RapidLaunch. The combination of a drag-and-drop builder, an AI template generator, and the rest of the kit (auth, payments, admin dashboard, analytics) at $69–$119 one-time is a better deal than buying Webflow plus any other starter on this list.

Try RapidLaunch and run your marketing site without a deploy pipeline.

HTML to PDF API: Convert Web Content to PDF Programmatically with Foxit

Lucien Chemaly — Thu, 16 Apr 2026 17:04:49 +0000

Your Puppeteer setup works fine at low volume. You launch a Chrome process, load the page, call page.pdf(), and write the bytes to disk. Then your invoice generation hits 500 documents per night, your report export feature goes live across three time zones simultaneously, and the wheels come off. Chrome processes time out waiting for JavaScript hydration. Memory climbs until your container OOMs. The font that renders correctly on your MacBook looks wrong on the Linux build server. You spend a Friday afternoon tuning networkidle2 timeouts per template instead of shipping features.

That failure mode comes from treating a rendering engine as a conversion service. Headless Chrome is a browser, and running it at production document volume means operating a browser fleet: process pooling, memory isolation, crash recovery, rendering consistency across OS environments. All of that infrastructure overhead comes directly out of engineering time.

A managed REST API sidesteps that entirely. You POST your HTML (or a URL), the service renders the PDF, and you download the result. The rendering infrastructure becomes the API provider's problem. This guide covers how to build that conversion pipeline end-to-end using Foxit PDF Services API, from authentication through batch processing and production error handling.

The Production Problem with Headless Browser PDF Conversion

A standard Puppeteer setup looks like this:

const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto(url, { waitUntil: "networkidle2" });
const pdf = await page.pdf({ format: "A4", printBackground: true });
await browser.close();

At five documents a day, this is fine. At five hundred concurrent, each puppeteer.launch() spins up a full Chromium process, roughly 100-200MB RSS on Linux. In a container with 2GB of memory and 20 concurrent requests, you're at the memory ceiling before accounting for the Node.js process or any other application memory.

The standard fix is a Chrome process pool (libraries like puppeteer-cluster or generic-pool). Now you're managing pool size tuning, handling pool exhaustion under burst traffic, and writing cleanup logic for crashed Chrome instances. You've added significant operational complexity to what started as a one-liner.

Font rendering is its own category of pain. Chrome on macOS uses CoreText. Chrome on Linux uses FreeType with fontconfig. The same CSS font-family: 'Inter' declaration produces visibly different output depending on whether Inter is installed as a system font or loaded via a @font-face declaration, and whether the fallback stack resolves differently across environments. Teams that ship invoice PDFs to customers discover this in production.

JavaScript execution adds another dimension. If your page renders a data table via a React component that fetches data on mount, networkidle2 is an unreliable wait condition. Network activity can go idle before the DOM finishes updating. You end up tuning waitForSelector or adding arbitrary timeouts per template, and those timeouts become technical debt that breaks when the page changes.

A managed REST API with consistent rendering environments and no infrastructure to maintain solves these problems at the architectural level.

How Cloud HTML-to-PDF APIs Handle Rendering

Cloud conversion APIs typically accept input in two modes: URL mode and file upload mode.

In URL mode, you pass a public URL. The API fetches the page, renders it, and returns a PDF. This works when your page is publicly accessible and all assets (fonts, images, stylesheets) load from the same domain or CDN. The tradeoff is that the API's rendering environment must reach your server, which creates a dependency on network reachability and your server's response time. If you're generating PDFs from an internal dashboard behind a VPN, URL mode doesn't work without additional networking.

In file upload mode, you construct the complete HTML file (with inlined CSS and assets where needed) and upload it to the API. The service processes the file and returns a PDF. This eliminates the external asset dependency and makes your conversion more deterministic. The same HTML file always produces the same PDF, regardless of what's deployed on your web server at the time.

Beyond input mode, rendering fidelity depends on several factors:

CSS @media print rules control what renders into the PDF. Navigation bars, sidebars, and hover states should be hidden via print stylesheets so they don't appear in the output.
Font loading strategy determines rendering consistency. Relying on system fonts produces different output across environments. Embedding fonts via @font-face with a CDN URL or base64-inlined data guarantees consistent rendering.
Page layout properties (paper size, margins, orientation) can be controlled through CSS @page rules embedded in the HTML itself. This keeps layout configuration in the document rather than in API parameters.
JavaScript execution matters for pages that render content dynamically. Some APIs wait for the page to stabilize before capturing; others capture immediately.

These factors are the same ones you'd manage with Puppeteer's page.pdf() options, but with a cloud API you handle them through your HTML and CSS rather than through in-process code.

Setting Up Foxit PDF Services API: Authentication and First Conversion

Foxit PDF Services API is a cloud-hosted REST API built on Foxit's proprietary PDF engine, backed by over 20 years of PDF technology development. Create an account at the Foxit Developer Portal (the Developer plan is free, includes 500 credits/year, and requires no credit card). Generate your API credentials (client_id and client_secret) from the Developer Dashboard.

Understanding the Async Workflow

Foxit PDF Services uses an asynchronous task-based workflow. Every operation follows the same pattern:

Submit the job (upload a file, or POST a URL)
Receive a taskId in the response
Poll the task status until it completes or fails
Download the result using the resultDocumentId from the completed task

This design handles long-running operations cleanly. A complex HTML page might take several seconds to render, and the async pattern means your client never blocks on a single HTTP request waiting for rendering to finish.

URL-to-PDF Conversion

For pages that are publicly accessible, URL-to-PDF is the simplest path. You POST the URL directly and the API fetches, renders, and converts it. The complete workflow in Python uses the requests library:

import os
import requests
from time import sleep

HOST = os.environ["FOXIT_API_HOST"]  # e.g., https://na1.fusion.foxit.com
CLIENT_ID = os.environ["FOXIT_CLIENT_ID"]
CLIENT_SECRET = os.environ["FOXIT_CLIENT_SECRET"]

AUTH_HEADERS = {
    "client_id": CLIENT_ID,
    "client_secret": CLIENT_SECRET,
}


def create_url_to_pdf_task(url: str) -> str:
    """Submit a URL for PDF conversion. Returns a taskId."""
    headers = {**AUTH_HEADERS, "Content-Type": "application/json"}
    response = requests.post(
        f"{HOST}/pdf-services/api/documents/create/pdf-from-url",
        json={"url": url},
        headers=headers,
    )
    response.raise_for_status()
    return response.json()["taskId"]


def poll_task(task_id: str, interval: int = 5) -> dict:
    """Poll until the task completes or fails. Returns the task status object."""
    headers = {**AUTH_HEADERS, "Content-Type": "application/json"}
    while True:
        response = requests.get(
            f"{HOST}/pdf-services/api/tasks/{task_id}",
            headers=headers,
        )
        response.raise_for_status()
        status = response.json()
        if status["status"] == "COMPLETED":
            return status
        elif status["status"] == "FAILED":
            raise RuntimeError(f"Task {task_id} failed: {status}")
        sleep(interval)


def download_document(document_id: str, output_path: str) -> None:
    """Download the resulting PDF by its document ID."""
    response = requests.get(
        f"{HOST}/pdf-services/api/documents/{document_id}/download",
        headers=AUTH_HEADERS,
        stream=True,
    )
    response.raise_for_status()
    with open(output_path, "wb") as f:
        for chunk in response.iter_content(chunk_size=8192):
            f.write(chunk)

# Full workflow: URL to PDF
task_id = create_url_to_pdf_task("https://example.com/invoice/1042")
result = poll_task(task_id)
download_document(result["resultDocumentId"], "invoice_1042.pdf")
print("PDF generated successfully.")

Three reusable functions map to the async workflow: create_url_to_pdf_task() submits a public URL and returns a taskId, poll_task() checks task status in a loop until it reaches COMPLETED or FAILED, and download_document() streams the resulting PDF to disk. The final three lines wire them together into the complete conversion pipeline.

Before running: Set your FOXIT_API_HOST, FOXIT_CLIENT_ID, and FOXIT_CLIENT_SECRET environment variables with the values from your Foxit Developer Dashboard. Never commit credentials to source control; use environment variables or a secrets manager.

HTML File-to-PDF Conversion

When your content isn't publicly accessible (internal dashboards, dynamically generated reports), you can upload an HTML file directly. This follows the same 4-step async pattern:

def upload_document(file_path: str) -> str:
    """Upload a file to Foxit. Returns a documentId."""
    with open(file_path, "rb") as f:
        response = requests.post(
            f"{HOST}/pdf-services/api/documents/upload",
            files={"file": f},
            headers=AUTH_HEADERS,
        )
    response.raise_for_status()
    return response.json()["documentId"]


def create_html_to_pdf_task(document_id: str) -> str:
    """Create an HTML-to-PDF conversion task. Returns a taskId."""
    headers = {**AUTH_HEADERS, "Content-Type": "application/json"}
    response = requests.post(
        f"{HOST}/pdf-services/api/documents/create/pdf-from-html",
        json={"documentId": document_id},
        headers=headers,
    )
    response.raise_for_status()
    return response.json()["taskId"]

# Full workflow: HTML file to PDF
doc_id = upload_document("report.html")
task_id = create_html_to_pdf_task(doc_id)
result = poll_task(task_id)
download_document(result["resultDocumentId"], "report.pdf")
print("HTML converted to PDF successfully.")

You first upload a local .html file via upload_document(), which returns a documentId referencing the uploaded file on Foxit's servers. Then create_html_to_pdf_task() submits that documentId for conversion. The rest of the workflow is identical: poll for completion, then download the result.

Note: Replace "report.html" with the path to your own HTML file. This code reuses the poll_task() and download_document() functions from the URL-to-PDF example above, so make sure both are defined in the same script.

URL-to-PDF skips the upload step because you POST the URL directly. HTML file conversion requires uploading the .html file first via the /documents/upload endpoint. Both use the same poll-and-download pattern after task creation.

Refer to the Foxit API documentation and the Postman workspace for the complete parameter reference, including any additional rendering options supported by these endpoints. The GitHub demo repository contains working examples in Python, Node.js, and PHP.

Controlling CSS and JavaScript Rendering in HTML-to-PDF Conversion

Regardless of which API you use for HTML-to-PDF conversion, output quality depends on how well you prepare the HTML. The rendering parameters live in your document, not in API request fields.

The most common rendering problem between "looks right in a browser" and "looks wrong in a PDF" is the CSS media type. By default, browsers render with screen styles, which means your navigation bar, sidebar, and hover states all appear in the output. For PDF output, you want your @media print rules to take over.

@media print {
  nav,
  .sidebar,
  .no-print {
    display: none;
  }

  body {
    font-size: 11pt;
    font-family: "Inter", Arial, sans-serif;
    color: #000;
  }

  .invoice-table {
    page-break-inside: avoid;
  }

  .page-header {
    page-break-before: always;
  }

  @page {
    size: A4;
    margin: 20mm 15mm;
  }
}

This stylesheet hides non-essential UI elements (navigation, sidebars) when printing, sets a clean body font, and uses page-break-inside: avoid to prevent the renderer from splitting a table row across pages. The nested @page rule sets the paper size and margins at the CSS level, so layout configuration stays in the document rather than in API parameters.

For font rendering consistency, don't rely on system fonts. Include a @font-face declaration in your HTML that loads from a CDN, or inline the font as base64:

<style>
  @font-face {
    font-family: "Inter";
    src: url("https://fonts.gstatic.com/s/inter/v13/UcCO3FwrK3iLTeHuS_fvQtMwCp50KnMw2boKoduKmMEVuLyfAZ9hiJ.woff2")
      format("woff2");
    font-weight: 400;
    font-style: normal;
  }
</style>

This embeds the Inter font directly in the HTML using a @font-face declaration pointing to Google Fonts. Inter renders in the PDF regardless of what fonts are installed in the API's container environment. The tradeoff is latency: the rendering engine fetches the font file during conversion. If you're running high-volume batch jobs, consider inlining the font as a base64 data URI to eliminate that network round trip.

For JavaScript-heavy pages, make sure the content has fully rendered before the API captures it. If you're using the URL-to-PDF endpoint, the API fetches and renders the live page, so your page's JavaScript will execute. For the HTML file upload path, keep your HTML self-contained with all data already rendered in the markup, rather than relying on client-side JavaScript to populate it after load.

Batch HTML-to-PDF Conversion at Scale

Sequential conversion is the naive starting point:

for invoice in invoices:
    doc_id = upload_document(invoice.html_path)
    task_id = create_html_to_pdf_task(doc_id)
    result = poll_task(task_id)
    download_document(result["resultDocumentId"], f"output/{invoice.id}.pdf")

Each invoice is processed one at a time, uploading, converting, polling, and downloading before moving to the next. Each iteration blocks on the poll loop before starting the next conversion. At a few seconds per document (upload, render, poll, download), 500 invoices could take over 30 minutes.

Concurrent dispatch with a semaphore to cap parallelism fixes that. Check your plan's rate limits before setting the semaphore ceiling in production.

import asyncio
import aiohttp
import os
from pathlib import Path

HOST = os.environ["FOXIT_API_HOST"]
CLIENT_ID = os.environ["FOXIT_CLIENT_ID"]
CLIENT_SECRET = os.environ["FOXIT_CLIENT_SECRET"]
MAX_CONCURRENT = 10  # Adjust based on your plan's rate limits


async def convert_one(
    session: aiohttp.ClientSession,
    sem: asyncio.Semaphore,
    invoice_id: str,
    html_path: str,
    output_dir: Path,
) -> tuple[str, bool]:
    async with sem:
        try:
            auth = {"client_id": CLIENT_ID, "client_secret": CLIENT_SECRET}

            # Step 1: Upload the HTML file
            with open(html_path, "rb") as f:
                form = aiohttp.FormData()
                form.add_field("file", f, filename="document.html")
                async with session.post(
                    f"{HOST}/pdf-services/api/documents/upload",
                    data=form,
                    headers=auth,
                ) as resp:
                    if resp.status != 200:
                        return invoice_id, False
                    upload_result = await resp.json()
                    doc_id = upload_result["documentId"]

            # Step 2: Create the conversion task
            async with session.post(
                f"{HOST}/pdf-services/api/documents/create/pdf-from-html",
                json={"documentId": doc_id},
                headers={**auth, "Content-Type": "application/json"},
            ) as resp:
                if resp.status != 200:
                    return invoice_id, False
                task_result = await resp.json()
                task_id = task_result["taskId"]

            # Step 3: Poll for completion
            while True:
                async with session.get(
                    f"{HOST}/pdf-services/api/tasks/{task_id}",
                    headers={**auth, "Content-Type": "application/json"},
                ) as resp:
                    status = await resp.json()
                    if status["status"] == "COMPLETED":
                        result_doc_id = status["resultDocumentId"]
                        break
                    elif status["status"] == "FAILED":
                        print(f"Task failed for {invoice_id}")
                        return invoice_id, False
                await asyncio.sleep(5)

            # Step 4: Download the result
            async with session.get(
                f"{HOST}/pdf-services/api/documents/{result_doc_id}/download",
                headers=auth,
            ) as resp:
                if resp.status == 200:
                    pdf_bytes = await resp.read()
                    (output_dir / f"{invoice_id}.pdf").write_bytes(pdf_bytes)
                    return invoice_id, True
                return invoice_id, False

        except Exception as e:
            print(f"Error converting {invoice_id}: {e}")
            return invoice_id, False


async def batch_convert(invoices: list[dict], output_dir: str = "output") -> dict:
    output_path = Path(output_dir)
    output_path.mkdir(exist_ok=True)

    sem = asyncio.Semaphore(MAX_CONCURRENT)
    connector = aiohttp.TCPConnector(limit=MAX_CONCURRENT)

    async with aiohttp.ClientSession(connector=connector) as session:
        tasks = [
            convert_one(session, sem, inv["id"], inv["html_path"], output_path)
            for inv in invoices
        ]
        results = await asyncio.gather(*tasks)

    succeeded = [r[0] for r in results if r[1]]
    failed = [r[0] for r in results if not r[1]]
    return {"succeeded": len(succeeded), "failed": failed}


# Usage
invoices = [
    {"id": "inv_1042", "html_path": "templates/invoice_1042.html"},
    {"id": "inv_1043", "html_path": "templates/invoice_1043.html"},
    # ... up to thousands of entries
]

result = asyncio.run(batch_convert(invoices))
print(f"Converted {result['succeeded']} PDFs. Failed: {result['failed']}")

asyncio and aiohttp let you process multiple conversions concurrently. The convert_one() function runs the full 4-step workflow (upload, create task, poll, download) for a single invoice, while batch_convert() dispatches all invoices in parallel, capped by a semaphore. Results are collected via asyncio.gather() and split into succeeded and failed lists.

Before running: Set FOXIT_API_HOST, FOXIT_CLIENT_ID, and FOXIT_CLIENT_SECRET as environment variables with your credentials from the Developer Dashboard. Adjust MAX_CONCURRENT based on your plan's rate limits, and update the invoices list with your actual file paths.

With MAX_CONCURRENT = 10 and several seconds per conversion (including polling), the batch processes 10 documents at a time. The semaphore prevents you from flooding the API with simultaneous requests and hitting the rate limit ceiling. asyncio is part of Python's standard library, so no additional dependencies beyond aiohttp are needed.

Credit consumption matters at scale. The Developer plan includes 500 credits/year. The Startup plan ($1,750/year) provides 3,500 credits. Each conversion typically costs 1 credit. For higher volumes, the Business plan ($4,500/year) includes 150,000 credits. Check your remaining credit balance via the Developer Dashboard before launching a large batch job.

For volumes beyond what a single process can handle efficiently, a queue-based architecture decouples submission from processing. Services like Amazon SQS or Redis Streams handle the message brokering:

App Server -> Message Queue (SQS / Redis Streams) -> Worker Pool (N workers)
  Worker: upload HTML -> create task -> poll -> download PDF -> store in S3/GCS
  Worker: update job status in Postgres / Redis

Each worker picks a job from the queue, runs the 4-step conversion workflow, writes the resulting PDF to S3 or GCS, and updates the job status in a database. This pattern handles burst volume naturally: jobs queue up during spikes, workers drain at the rate the API allows, and your app server is never blocked waiting for conversions to complete.

Production Deployment Patterns for HTML-to-PDF Pipelines

Error Handling and Retry Logic

Map HTTP status codes to decisions before writing any retry logic, because not all errors warrant a retry.

A 400 Bad Request means your request body is malformed. Retrying the same payload returns another 400, so fix the payload. A 429 Too Many Requests and a 503 Service Unavailable are transient: back off and retry. A FAILED task status means the conversion itself failed (possibly due to invalid HTML or unreachable URLs). Check the task response for diagnostic details.

import time
import random
import requests
from requests.exceptions import RequestException

PERMANENT_ERRORS = {400, 401, 403, 422}
TRANSIENT_ERRORS = {429, 500, 502, 503, 504}


def post_with_retry(
    url: str,
    max_retries: int = 4,
    base_delay: float = 1.0,
    **kwargs,
) -> requests.Response:
    """POST with exponential backoff and jitter for transient errors."""
    for attempt in range(max_retries + 1):
        try:
            response = requests.post(url, timeout=60, **kwargs)

            if response.status_code in range(200, 300):
                return response

            if response.status_code in PERMANENT_ERRORS:
                raise ValueError(
                    f"Permanent error {response.status_code}: {response.text}"
                )

            if response.status_code in TRANSIENT_ERRORS:
                if attempt == max_retries:
                    raise RuntimeError(
                        f"Max retries exceeded. Last status: {response.status_code}"
                    )
                delay = base_delay * (2 ** attempt) + random.uniform(0, 0.5)
                print(f"Transient error {response.status_code}. Retrying in {delay:.1f}s...")
                time.sleep(delay)

        except RequestException as e:
            if attempt == max_retries:
                raise
            delay = base_delay * (2 ** attempt) + random.uniform(0, 0.5)
            time.sleep(delay)

    raise RuntimeError("Unexpected: exhausted retries without returning or raising")

# Usage with the URL-to-PDF endpoint
auth_headers = {
    "client_id": CLIENT_ID,
    "client_secret": CLIENT_SECRET,
    "Content-Type": "application/json",
}

response = post_with_retry(
    f"{HOST}/pdf-services/api/documents/create/pdf-from-url",
    json={"url": "https://example.com/invoice/1042"},
    headers=auth_headers,
)
task_id = response.json()["taskId"]

Every POST request goes through a retry loop with exponential backoff. The function distinguishes between permanent errors (like 400 or 401, which you shouldn't retry) and transient errors (like 429 or 503, which resolve on their own). Each retry doubles the wait time and adds random jitter to avoid synchronized retry waves.

Before running: Replace CLIENT_ID, CLIENT_SECRET, and HOST with your Foxit credentials and API host, or load them from environment variables as shown in the earlier examples.

The jitter (random.uniform(0, 0.5)) prevents a thundering herd where every worker wakes up and retries simultaneously after a 429 burst. Plain exponential backoff produces synchronized retry waves when all workers hit the rate limit at the same time.

Output Optimization: Compression and Linearization

After conversion, you can chain additional PDF operations using the same async pattern. Upload the resulting PDF, call the compression or linearization endpoint, poll, and download the optimized version.

For PDFs served directly in a browser, linearization enables Fast Web View, which lets the browser display page one while the rest of the file downloads:

def compress_and_linearize(input_pdf_path: str, output_path: str) -> None:
    """Compress a PDF, then linearize it for fast web viewing."""
    auth = {"client_id": CLIENT_ID, "client_secret": CLIENT_SECRET}
    json_headers = {**auth, "Content-Type": "application/json"}

    # Upload the PDF
    doc_id = upload_document(input_pdf_path)

    # Compress
    resp = requests.post(
        f"{HOST}/pdf-services/api/documents/modify/pdf-compress",
        json={"documentId": doc_id, "compressionLevel": "MEDIUM"},
        headers=json_headers,
    )
    resp.raise_for_status()
    task = poll_task(resp.json()["taskId"])
    compressed_doc_id = task["resultDocumentId"]

    # Linearize the compressed result (no need to re-upload; use the resultDocumentId)
    resp = requests.post(
        f"{HOST}/pdf-services/api/documents/optimize/pdf-linearize",
        json={"documentId": compressed_doc_id},
        headers=json_headers,
    )
    resp.raise_for_status()
    task = poll_task(resp.json()["taskId"])

    # Download the final optimized PDF
    download_document(task["resultDocumentId"], output_path)

You chain two PDF operations back-to-back here. First, you upload the PDF and compress it at MEDIUM level (valid options are LOW, MEDIUM, and HIGH). Once compression completes, you pass the resultDocumentId directly into the linearization step, which avoids a second upload. The final download gives you a PDF that's both smaller and optimized for progressive loading in browsers.

Note: This function reuses upload_document(), poll_task(), and download_document() from the earlier examples. Make sure those functions are defined in the same script with your credentials configured. The Foxit developer blog post on chaining PDF actions covers this pattern in detail.

Monitoring and Secret Management

Monitor three things per conversion job: how long each call takes (to spot API degradation early), credits consumed per job type (to forecast when you'll hit your plan ceiling), and failure rate broken down by error code (to catch template regressions before customers do). Set an alert when your remaining credits fall below 20% of the plan allocation. The Foxit Developer Dashboard surfaces real-time usage data worth checking before kicking off large batch runs.

Store API credentials in environment variables or a secrets manager (AWS Secrets Manager, HashiCorp Vault, GCP Secret Manager). When team members leave or you suspect a credential leak, rotate them from the Developer Dashboard. New credentials can be generated and old ones revoked without downtime, as long as you update your environment before revoking.

Start Converting HTML to PDF

The Foxit Developer plan is free, requires no credit card, and gives you 500 credits to start with. Grab your client_id and client_secret from the Developer Dashboard, then either clone the demo repository for ready-made examples in Python, Node.js, and PHP, or drop the URL-to-PDF snippet from this guide into a script and run it against any public page.

Once your first conversion comes back, check credit usage in the Dashboard to project costs at your production volume. If you need more throughput, the Startup plan ($1,750/year for 3,500 credits) is self-serve with no sales call.

Get started for free on the Foxit Developer Portal