How to append PDF rows to Google Sheets with the API

Google Sheets is the safest first destination for PDF extraction workflows. Finance, operations, and customer-success teams already know how to filter rows, add formulas, and export CSV. The integration job is simple: when okraPDF finishes processing a PDF, append one typed row per document or one row per line item into a sheet.

This is API-feasible today. The Google Sheets API spreadsheets.values.append method appends values to the end of a range. okraPDF also has a native Google Sheets export for Data Tables today, but that current native path creates a new spreadsheet. If you need ongoing append into an existing sheet, use the API pattern below through Zapier, Make, n8n, or your own backend.

Recommended architecture

Use okraPDF as the extraction system of record and Google Sheets as the operational view.

Part	System	Responsibility
Source PDF	okraPDF upload, email inbox, Drive trigger, or API	Receives the document
Processing event	okraPDF webhook document.processed	Signals that extraction is complete
Row mapper	Zapier, Make, n8n, or your backend	Converts JSON fields into columns
Destination	Google Sheets API	Appends rows

Do not append a row on upload accepted unless you only need an intake log. For extracted data, wait for document.processed.

Sheet design

Create a worksheet with stable headers before wiring automation. Good invoice headers are:

• received_at
• filename
• document_id
• vendor_name
• invoice_number
• invoice_date
• due_date
• currency
• subtotal
• tax
• total
• hosted_url
• review_status

For line items, use a second tab keyed by document_id and line_index. Keep header-level fields and line-item fields separate. A single wide sheet with repeated line-item columns becomes hard to query and hard to repair.

Option A: Use Zapier

This is the fastest non-code path.

1. Create a Zap with okraPDF as the trigger.
2. Choose the PDF Ready event, which maps to document.processed.
3. Add Google Sheets as the action.
4. Choose Create Spreadsheet Row or Create Multiple Spreadsheet Rows.
5. Map okraPDF fields into the sheet columns.

Use Create Multiple Spreadsheet Rows if your extraction output contains a line-item array. Use one normal Create Spreadsheet Row if each PDF should produce one summary row.

Option B: Use Make

Make is useful when you need branching, retries, or array handling.

1. Start with Webhooks > Custom webhook.
2. Paste the Make webhook URL into okraPDF webhooks.
3. Select document.processed and document.failed.
4. Add a Google Sheets module.
5. If line items are present, add an iterator before the Sheets module.

Make’s HTTP and webhook modules can also call okraPDF directly for upload-first flows, so the same scenario can ingest PDFs and write rows.

Option C: Use n8n

n8n is the cleanest self-hosted option.

1. Add a Webhook node for okraPDF events.
2. Add an IF node for body.type === "document.processed".
3. Add a Set or Code node to flatten the extraction payload.
4. Add a Google Sheets node to append rows.

For high-volume flows, put a queue between the webhook and Sheets append. Google Sheets is not a database; it is a working surface.

Option D: Use your backend

If this is part of a product, write the append yourself.

The flow is:

1. Receive the okraPDF webhook.
2. Verify X-Okra-Signature.
3. Flatten data.extracted into a row array in the same order as your headers.
4. Call spreadsheets.values.append.
5. Store the returned spreadsheet row range with your document record.

Use a service account only when your product owns the spreadsheet. Use OAuth when the customer owns the spreadsheet.

Failure handling

Build a failure row. When okraPDF sends document.failed, append a row with filename, document ID, error message, and review_status = "failed". This gives operations a queue instead of a silent gap.

Also add idempotency. Store the okraPDF event ID or document_id before writing. If a webhook retries, skip the duplicate or update the existing row.

When to avoid Sheets

Do not use Sheets as the source of truth for large document volumes, audit trails, or multi-user approvals. Use it as a review and export layer. Keep okraPDF document IDs, hosted URLs, and source payloads in your own system so the sheet can be rebuilt if someone sorts, deletes, or edits cells by mistake.