Automate PDF table extraction

Guide

Automating PDF table extraction with the API

The playground is the right tool for one PDF on a Thursday. It is the wrong tool for a folder that arrives every Monday. The API is the same extractor, without the browser: POST /v1/extract-tables returns the JSON, and POST /v1/invoice-xlsx returns the checksummed workbook. This guide is the boring setup that keeps a loop from posting garbage: auth, limits, a curl you can copy, and the fields worth branching on.

When to leave the playground

Stay on the site while you are still learning the PDF. Download one JSON, check three cells, and read the extract guide if the shape surprises you. Move to the API when the same kind of file shows up again and the cleanup is written down. Automating a layout you have not checked once just produces a pile of confident JSON.

The playground does not need a key because the browser request is same-origin. A script is not the playground. Send X-API-Key or Authorization: Bearer YOUR_KEY. Ask for a key on the contact page. There is no signup form and no customer login. RapidAPI callers authenticate on RapidAPI's side. Zapier stores the key in the connection. Do not put the key in a query string or in a front-end bundle. A key in a public repository will be used by someone else within the hour, and the rate limit will be theirs and yours together.

One file, two ways to send it

Upload the bytes when you have the file. The multipart field name is file. The limit is 500 MB. The request can run for about three minutes, which matters for a dense report and does not matter for a one-page invoice.

curl -X POST https://tablejson.com/v1/extract-tables \
  -H "X-API-Key: YOUR_KEY" \
  -F "file=@invoice.pdf" \
  -o invoice.json

Send a URL when the PDF is already on a public HTTPS address. The body is JSON, and the fetch limit is 50 MB. Localhost, link-local, and private network addresses are refused, so this is not a way to point the server at a file inside your office.

curl -X POST https://tablejson.com/v1/extract-tables \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file":"https://tablejson.com/sample-mini.pdf"}'

Invoices use the other route. Without a query, the body is an xlsx file. With ?format=json, the body is the checksum preview. Save the preview next to the workbook if a later job needs to read checksum without opening Excel.

curl -X POST "https://tablejson.com/v1/invoice-xlsx?format=json" \
  -H "X-API-Key: YOUR_KEY" \
  -F "file=@invoice.pdf"

GET /v1/example and GET /v1/invoice-example return canned samples. They do not read a PDF. Useful in a hub tester. Useless in a pipeline. GET /v1/health is the ping that should sit in front of a deploy.

A folder loop that keeps the failures

This is deliberately plain bash. It uploads each PDF, writes the JSON beside it, and moves on. It does not retry a scan until the scan grows a text layer.

mkdir -p out
for pdf in incoming/*.pdf; do
  base=$(basename "$pdf" .pdf)
  code=$(curl -sS -o "out/$base.json" -w "%{http_code}" \
    -X POST https://tablejson.com/v1/extract-tables \
    -H "X-API-Key: $TABLEJSON_API_KEY" \
    -F "file=@$pdf")
  echo "$code $pdf"
done

Twenty requests a minute per IP is the limit. A tight loop over a large folder will see 429 and retry_after_seconds. Sleep that long and continue. Do not fire five parallel workers from the same address and call it a speedup. The server also only parses a couple of PDFs at a time, so extra concurrency waits anyway.

After the loop, branch on the body, not only on the HTTP code. A 200 with status: "success" can still be an empty extract.

401 and UNAUTHORIZED — the key is missing or wrong. Fix the header. Do not retry.
400 with INVALID_PDF or INVALID_FILE_TYPE — not a readable text PDF. Quarantine the file.
413 — over 500 MB, or over 50 MB on a URL fetch.
429 — back off.
200 and tables_found: 0 — almost always a scan or a page with no text. Send it to OCR or to a person. See text-layer versus scanned.
200 and a single table whose headers are line_number and extracted_content — text existed and never split into columns. Do not import it as transactions.
Invoice checksum of PASS — safe to file, after you have spot-checked that vendor once.
Any invoice FAIL: — keep the xlsx, do not post the total. FAIL: no text layer is a scan. A remainder is a math disagreement worth a human.

Where Zapier and RapidAPI fit

Zapier has two actions, Extract Tables From PDF and Invoice PDF to Excel. The key lives in the connection. The PDF has to be a file the Zap can hand over, from email, Drive, or a previous step. The same limits apply. A Zap that extracts and then immediately adds a row to a sheet should include a filter on tables_found or on the checksum. Otherwise a scanned attachment becomes a blank row that looks like success.

RapidAPI is the same API behind their gateway. Import openapi.json when the routes change. Hub testers should run the example GETs first. Those responses are small so the browser does not choke on a giant body. Your production calls should be the POST routes, with a real file.

Webhooks by Zapier, or any HTTP client, can call the routes directly if you would rather not wait on an app listing. Method POST, header X-API-Key, body multipart field file. The docs page has the same examples with less story around them: tablejson.com/docs.

Keep the output, because the server will not

Nothing in this API remembers your PDF. The multipart upload is a temp file, deleted when the response finishes. The JSON in the response is the copy you own. Write it to disk, to your bucket, or to the Zap's storage. If you need the extract again tomorrow, read your copy. Uploading the same PDF again runs the parser again. It does not look up a previous result. That also means a bugfix on our side only shows up when you re-run. Pin a few sample PDFs in your repo, the tiny public ones or your own fixtures, and re-run them when you bump the client.

Log the HTTP code, tables_found, total_pages, and the execution time. Do not log the PDF and do not log the rows if those rows are someone's statement. The balance check from the statement guide, or the invoice checksum, belongs in the job. An automated extract without that check is a faster way to be wrong.